# Agentic IDEs and CLIs
Source: https://docs.pinecone.io/guides/get-started/ai-coding-tools

Use Pinecone with agentic IDEs and CLIs like Claude Code, Gemini CLI, and Cursor via MCP server, plugins, and agent skills for vector search.

Pinecone provides official plugins, extensions, and agent skills for agentic IDEs and CLIs. Use the Pinecone [MCP server](/guides/operations/mcp-server) (Model Context Protocol) and built-in skills to manage vector database indexes, run semantic search, and build RAG applications — all through natural language in your development environment. For direct, scriptable access from the same terminal, the [Pinecone CLI](/reference/cli/quickstart) (`pc`) lets you manage indexes, namespaces, and records without an agent in the loop.

## Choose your tool

<CardGroup>
  <Card title="Claude Code Plugin" icon="plug" href="/integrations/claude-code">
    Official Pinecone plugin for Claude Code with skills, MCP tools, and slash commands.
  </Card>

  <Card title="Gemini CLI Extension" icon="terminal" href="/integrations/gemini-cli">
    Official Pinecone extension for Gemini CLI with skills and MCP tools.
  </Card>

  <Card title="Cursor Plugin" icon="plug" href="/integrations/cursor">
    Official Pinecone plugin for Cursor with skills, MCP tools, and slash commands.
  </Card>

  <Card title="Agent Skills" icon="layer-group" href="/integrations/agent-skills">
    Universal skills library for GitHub Copilot, Codex, and other agentic IDEs.
  </Card>

  <Card title="MCP Server" icon="server" href="/guides/operations/mcp-server">
    Connect any MCP-compatible client to Pinecone for index management and search.
  </Card>

  <Card title="Pinecone CLI" icon="rectangle-terminal" href="/reference/cli/quickstart">
    Direct terminal access to Pinecone — manage indexes, namespaces, and records with `pc` commands.
  </Card>
</CardGroup>

## Which tool should I use?

| If you use...                                                                                                     | Install...                                                   | Command                                                                         |
| ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------- |
| [Claude Code](https://claude.ai/code)                                                                             | [Pinecone plugin for Claude Code](/integrations/claude-code) | `claude plugin install pinecone`                                                |
| [Gemini CLI](https://github.com/google-gemini/gemini-cli)                                                         | [Pinecone Gemini CLI extension](/integrations/gemini-cli)    | `gemini extensions install https://github.com/pinecone-io/gemini-cli-extension` |
| [Cursor](https://www.cursor.com/)                                                                                 | [Pinecone Cursor plugin](/integrations/cursor)               | `/add-plugin pinecone`                                                          |
| [GitHub Copilot](https://github.com/features/copilot), [Codex](https://chatgpt.com/codex), or another agentic IDE | [Pinecone Agent Skills](/integrations/agent-skills)          | `npx skills add pinecone-io/skills`                                             |
| Claude Desktop, Antigravity, or another MCP client                                                                | [Pinecone MCP server](/guides/operations/mcp-server)         | See [MCP server setup](/guides/operations/mcp-server)                           |
| Your terminal directly (no agent)                                                                                 | [Pinecone CLI](/reference/cli/quickstart)                    | `brew install pinecone-io/tap/pinecone`                                         |

All tools require a [Pinecone API key](https://app.pinecone.io/organizations/-/keys). Sign up for a free account at [app.pinecone.io](https://app.pinecone.io).

## What's included

Each tool provides access to the following Pinecone skills:

| Skill                | Description                                                                                                                                                     |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **quickstart**       | Step-by-step onboarding — create an index, upload data, and run your first search.                                                                              |
| **query**            | Search integrated indexes using natural language text via the Pinecone MCP.                                                                                     |
| **assistant**        | Create, manage, and chat with Pinecone Assistants for document Q\&A with citations.                                                                             |
| **cli**              | Use the Pinecone CLI for terminal-based index and vector management.                                                                                            |
| **full-text-search** | Create, ingest into, and query a Pinecone full-text-search (FTS) index using the preview API.                                                                   |
| **n8n**              | Build [n8n](/integrations/n8n) workflows with the Pinecone Assistant node or Pinecone Vector Store, including best practices and full workflow JSON generation. |
| **mcp**              | Reference for all available Pinecone MCP server tools and their parameters.                                                                                     |
| **pinecone-docs**    | Curated links to official Pinecone documentation, organized by topic.                                                                                           |
| **help**             | Overview of all skills and what you need to get started.                                                                                                        |

In addition, the [Pinecone MCP server](/guides/operations/mcp-server) provides tools for listing indexes, creating indexes, upserting records, searching, reranking, and more.


# Concepts
Source: https://docs.pinecone.io/guides/get-started/concepts

Learn core Pinecone concepts (organizations, projects, indexes, documents, namespaces, dense and sparse vectors) and how they relate.

<img />

<img />

## Organization

An organization is a group of one or more [projects](#project) that use the same billing. Organizations allow one or more [users](#user) to control billing and permissions for all of the projects belonging to the organization.

For more information, see [Understanding organizations](/guides/organizations/understanding-organizations).

## Project

A project belongs to an [organization](#organization) and contains one or more [indexes](#index). Each project belongs to exactly one organization, but only [users](#user) who belong to the project can access the indexes in that project. [API keys](#api-key) and [Assistants](#assistant) are project-specific.

For more information, see [Understanding projects](/guides/projects/understanding-projects).

## Index

Pinecone [serverless indexes](/guides/index-data/indexing-overview) hold your data as [documents](#document) or [records](#record), depending on how the index was created: an index created with a document schema holds documents, while an index created with a dense or sparse vector type holds records. A document is a JSON object with ranking fields that Pinecone indexes according to a schema you define, plus any number of metadata fields. A single index with a document schema can mix multiple ranking field types: a `dense_vector` field for [semantic search](#index-with-dense-vectors), a `sparse_vector` field for [sparse-vector retrieval](#index-with-sparse-vectors), and one or more `string` fields with `full_text_search` enabled for [full-text search](#full-text-search) with BM25 and Lucene queries. Metadata fields (anything else you upsert) are auto-indexed for filtering at upsert time, no schema declaration required.

One index per use case is the typical pattern. Because a document can combine vectors, text, and metadata in the same record, a single index often covers what previously required two — pick the ranking signal per query with `score_by`.

### Full-text search

Full-text search is **BM25 token matching with Lucene query syntax** over text fields in your schema — `string` fields you've declared with `full_text_search` so their content is indexed for token-level retrieval. "Text field" is the colloquial name; the JSON `type` is `string`. No model required — Pinecone handles tokenization, IDF, and length normalization at index time and BM25 scoring at query time. "Token" here means a unit produced by Pinecone's text analyzer (whitespace + punctuation split, lowercased, optionally stemmed) — not the subword unit a dense or sparse embedding model uses internally. See [Tokens and analyzers](/guides/search/full-text-search#tokens-and-analyzers) for the full pipeline.

How it works:

1. You upsert data as JSON [documents](#document).
2. You declare each ranking field's type in the index schema: `dense_vector`, `sparse_vector`, or `string` with `full_text_search` (indexed for BM25 ranking and Lucene queries). Metadata fields are not declared in the schema.
3. Pinecone indexes each ranking field according to its declared type and auto-indexes any other fields on the document for metadata filtering.

When you search, you choose a scoring method via `score_by`. The literal value of `type` selects the method: `text` (BM25 token matching on a single text field), `query_string` ([Lucene query syntax](/guides/search/full-text-search#query-syntax-reference) across one or more text fields, including cross-field boolean queries), `dense_vector` (vector similarity), or `sparse_vector` (sparse-vector similarity). Any scoring method can be combined with metadata filters — including logical operators (`$and`, `$or`, `$not`), existence checks (`$exists`), and the text-match operators (`$match_phrase`, `$match_all`, `$match_any`) for phrase and token matching against text fields.

Use full-text search for keyword and phrase search over text content — product names, identifiers, technical terms, code, and other cases where queries and documents share specific tokens. For sparse-vector retrieval with a learned encoder (such as [`pinecone-sparse-english-v0`](/models/pinecone-sparse-english-v0)), see [Index with sparse vectors](#index-with-sparse-vectors). For semantic similarity over natural-language queries, see [Index with dense vectors](#index-with-dense-vectors).

Learn more:

* [Full-text search](/guides/search/full-text-search)
* [Document](#document)

### Index with dense vectors

These indexes store records that each have one [dense vector](#dense-vector). A dense vector is a series of numbers that represent the meaning and relationships of text, images, or other data. Each vector is a point in a multidimensional space; each number is a coordinate in that space. Vectors that are closer together in that space are semantically similar.

When you query an index with dense vectors, Pinecone retrieves records whose vectors are most semantically similar to the query. This is often called **semantic search**, nearest neighbor search, similarity search, or just vector search.

<Note>
  If records in an index with dense vectors also have a [sparse vector](#sparse-vector), the index supports single-index [hybrid search](/guides/search/hybrid-search#use-a-single-index-for-dense-and-sparse-vectors) on the same records. This single-index pattern uses the vector API and isn't available for indexes with document schemas. To combine a lexical signal with a dense signal in an index with a document schema, restrict a dense search with a text-match filter or run separate searches and merge the results client-side; see [Hybrid search](/guides/search/hybrid-search).
</Note>

### Index with sparse vectors

These indexes store records that each have one [sparse vector](#sparse-vector) — a vector with very high dimensionality but only a small number of non-zero values. Each dimension typically corresponds to a token in a vocabulary; the non-zero values represent the importance of those tokens in a document.

When you search an index with sparse vectors, Pinecone retrieves records whose vectors share the most weighted tokens with the query vector. This is often called **sparse-vector retrieval** or **sparse-vector lexical search**.

Sparse vectors are produced by a sparse embedding model. Pinecone hosts [`pinecone-sparse-english-v0`](/models/pinecone-sparse-english-v0), a learned-sparse encoder that predicts per-token weights and includes term expansion (related concepts that don't appear in the source text). You can also bring your own sparse model.

<Note>
  **Sparse-vector lexical search vs. full-text search.** Both retrieve documents using token-level signals over an inverted index. They differ in how tokens are weighted: [full-text search](#full-text-search) uses **BM25** — a statistical scoring function with no machine learning, computed at query time over your raw text fields. Sparse-vector lexical search uses a **learned sparse encoder** that produces token weights at index time, often with term expansion. Use full-text search when you want a strong baseline with no model to manage; use sparse vectors when a learned encoder (yours or Pinecone's hosted one) better captures your domain's term importance and synonyms.

  A useful gradient: dense ranks on **concept** (semantic similarity), full-text search ranks on **strict character-level token matching** (BM25), and sparse-vector lexical search sits **between them** — token-aware, but with learned per-token weights and term expansion. Sparse vectors carry no positional information, so phrase matching (`"machine learning"` as a contiguous span) requires full-text search, not sparse.
</Note>

## Namespace

A namespace is a partition within an index. It divides [records](#record) into separate groups so that each query scans only one namespace (faster lookups) and each customer's data can be isolated from another customer's (multitenant isolation).

All [upserts](/guides/index-data/upsert-data), [queries](/guides/search/search-overview), and other data read and write operations always target one namespace:

<img />

<img />

For more information, see [Use namespaces](/guides/index-data/indexing-overview#namespaces).

## Record

A record is the unit of data for [indexes with dense vectors](#index-with-dense-vectors) and [indexes with sparse vectors](#index-with-sparse-vectors): a [record ID](#record-id), one vector (or both vector types for single-index [hybrid search](/guides/search/hybrid-search)), and optional [metadata](#metadata). With [integrated embedding](/guides/index-data/indexing-overview#integrated-embedding) you can upsert raw text instead of a vector, and Pinecone embeds it at index time. When an item has more than one searchable field — say, a text field ranked by BM25 alongside a `dense_vector` field for similarity — model it as a [document](#document).

For more information, see [Upsert data](/guides/index-data/upsert-data).

## Document

A document is the unit of data in an index with a document schema — a JSON object with a required `_id` field, the ranking fields declared in the index's schema, and any number of metadata fields. Documents support multiple ranking field types in a single record: a `dense_vector` field (for [semantic search](#index-with-dense-vectors)), a `sparse_vector` field (for [sparse-vector retrieval](#index-with-sparse-vectors)), and one or more `string` fields with `full_text_search` enabled (for [full-text search](#full-text-search)). A single document can carry vectors, text, and metadata together, and you choose the scoring method per query via `score_by`. Documents are the recommended shape for new multi-field and full-text workloads; vector-only indexes continue to use [records](#record). Both APIs are fully supported.

Document fields can hold structured values: a metadata `string_list` field holds an array of strings; a `dense_vector` field holds an array of floats; a `sparse_vector` field is an object with two parallel arrays — `indices` (token positions) and `values` (token weights).

A schema can declare up to 100 `string` fields with `full_text_search` enabled, but at most one `dense_vector` field and at most one `sparse_vector` field per index.

Metadata fields are not declared in the schema. Any field on an upserted document that is not declared in the schema is stored, returned via `include_fields`, and automatically indexed for filtering. Pinecone infers metadata field types (string, number, boolean, array of strings) from the values you upsert.

Field names must be unique, non-empty strings, must not start with `_` (reserved for system-managed fields like `_id` and `_score`) or `$` (reserved for filter operators), and are limited to 64 bytes.

For more information, see [Full-text search](/guides/search/full-text-search).

### Record ID

A record ID is a record's unique ID. [Use ID prefixes](/guides/index-data/data-modeling#use-structured-ids) that reflect the type of data you're storing.

### Dense vector

A dense vector, also referred to as a vector embedding or simply a vector, is a series of numbers that represent the meaning and relationships of data. Each vector is a point in a multidimensional space; each number is a coordinate in that space. Vectors that are closer together in that space are semantically similar.

Dense vectors are stored in indexes (see [Index with dense vectors](#index-with-dense-vectors)).

You use a dense embedding model to convert data to dense vectors. The embedding model can be external to Pinecone or [hosted on Pinecone infrastructure](/guides/index-data/create-an-index#embedding-models) and integrated with an index.

For more information about dense vectors, see [What are vector embeddings?](https://www.pinecone.io/learn/vector-embeddings/).

### Sparse vector

Sparse vectors are often used to represent documents or queries in a way that captures keyword information. Each dimension in a sparse vector typically represents a word from a dictionary, and the non-zero values represent the importance of these words in the document.

Sparse vectors have a large number of dimensions, but a small number of those values are non-zero. Because most values are zero, Pinecone stores sparse vectors efficiently by keeping only the non-zero values along with their corresponding indices.

Sparse vectors are stored in indexes (see [Index with sparse vectors](#index-with-sparse-vectors)) and can also coexist with dense vectors in a single index for [hybrid search](/guides/search/hybrid-search#use-a-single-index-for-dense-and-sparse-vectors) on the vector API. To combine a lexical signal with a dense signal in an index with a document schema, restrict a dense search with a text-match filter on a `string` field with `full_text_search` enabled or run separate searches and merge the results client-side. To convert data to sparse vectors, use a sparse embedding model. The embedding model can be external to Pinecone or [hosted on Pinecone infrastructure](/guides/index-data/create-an-index#embedding-models) and integrated with an index.

For more information about sparse vectors, see [Sparse retrieval](https://www.pinecone.io/learn/sparse-retrieval/).

### Metadata

Metadata is additional information included in a record to provide more context and enable additional [filtering capabilities](/guides/index-data/indexing-overview#metadata). For example, the original text that was embedded can be stored in the metadata.

## Other concepts

Although not represented in the diagram above, Pinecone also contains the following concepts:

* [API key](#api-key)
* [User](#user)
* [Backup or collection](#backup-or-collection)
* [Pinecone Inference](#pinecone-inference)
* [Read unit (RU)](#read-unit-ru)
* [Write unit (WU)](#write-unit-wu)

### API key

An API key is a unique token that [authenticates](/reference/api/authentication) and authorizes access to the [Pinecone APIs](/reference/api/introduction). API keys are project-specific.

### User

A user is a member of organizations and projects. Users are assigned specific roles at the organization and project levels that determine the user's permissions in the [Pinecone console](https://app.pinecone.io).

For more information, see [Manage organization members](/guides/organizations/manage-organization-members) and [Manage project members](/guides/projects/manage-project-members).

### Backup or collection

A backup is a static copy of a serverless index.

Backups only consume storage. They are non-queryable representations of a set of records. You can create a backup from an index, and you can create a new index from that backup. The new index configuration can differ from the original source index: for example, it can have a different name. However, it must have the same number of dimensions and similarity metric as the source index.

For more information, see [Understanding backups](/guides/manage-data/backups-overview).

### Pinecone Inference

Pinecone Inference is an API service that provides access to [embedding models](/guides/index-data/create-an-index#embedding-models) and [reranking models](/guides/search/rerank-results#reranking-models) hosted on Pinecone's infrastructure.

### Read unit (RU)

A read unit (RU) is the unit Pinecone uses to measure and price the cost of read requests to a serverless index, including [query](/guides/manage-cost/understanding-cost#query), [fetch](/guides/manage-cost/understanding-cost#fetch), and [list](/guides/manage-cost/understanding-cost#list).

For how read units are calculated, see [Understanding cost](/guides/manage-cost/understanding-cost#read-units).

### Write unit (WU)

A write unit (WU) is the unit Pinecone uses to measure and price the cost of write requests to a serverless index, including [upsert](/guides/manage-cost/understanding-cost#upsert), [update](/guides/manage-cost/understanding-cost#update), and [delete](/guides/manage-cost/understanding-cost#delete).

For how write units are calculated, see [Understanding cost](/guides/manage-cost/understanding-cost#write-units).

## Learn more

* [Vector database](https://www.pinecone.io/learn/vector-database/)
* [Pinecone APIs](/reference/api/introduction)
* [Approximate nearest neighbor (ANN) algorithms](https://www.pinecone.io/learn/a-developers-guide-to-ann-algorithms/)
* [Retrieval augmented generation (RAG)](https://www.pinecone.io/learn/retrieval-augmented-generation/)
* [Image search](https://www.pinecone.io/learn/series/image-search/)
* [Tokenization](https://www.pinecone.io/learn/tokenization/)


# Architecture
Source: https://docs.pinecone.io/guides/get-started/database-architecture

Learn how Pinecone's serverless architecture (API gateway, control plane, data plane, and object storage) powers vector search at scale.

## Overview

Pinecone runs as a managed service on AWS, GCP, and Azure cloud platforms. When you send a request to Pinecone, it goes through an [API gateway](#api-gateway) that routes it to either a global [control plane](#control-plane) or a regional [data plane](#data-plane). All your vector data is stored in highly efficient, distributed [object storage](#object-storage).

<img />

<img />

### API gateway

Every request to Pinecone includes an [API key](/guides/projects/manage-api-keys) that's assigned to a specific [project](/guides/projects/understanding-projects). The API gateway first validates your API key to make sure you have permission to access the project. Once validated, it routes your request to either the global control plane (for managing projects and indexes) or a regional data plane (for reading and writing data), depending on what you're trying to do.

### Control plane

The global control plane manages your organizational resources like projects and indexes. It uses a dedicated database to keep track of all these objects. The control plane also handles billing, user management, and coordinates operations across different regions.

### Data plane

The data plane handles all requests to write and read records in [indexes](/guides/index-data/indexing-overview) within a specific [cloud region](/guides/index-data/create-an-index#cloud-regions). Each index is divided into one or more logical [namespaces](/guides/index-data/indexing-overview#namespaces), and all your data read and write requests target a specific namespace.

Pinecone separates write and read operations into different paths, with each scaling independently based on demand. This separation ensures that your queries never slow down your writes, and your writes never slow down your queries.

### Object storage

For each namespace in a serverless index, Pinecone organizes records into immutable files called slabs. These slabs are [optimized for fast querying](#index-builder) and stored in distributed object storage that provides virtually unlimited scalability and high availability.

## Write path

<img />

<img />

### Request log

When you send a write request (to add, update, or delete records), the [data plane](#data-plane) first logs the request details with a unique sequence number (LSN). This ensures all operations happen in the correct order and provides a way to track the state of the index.

Pinecone immediately returns a `200 OK` response, guaranteeing that your write is durable and won't be lost. The system then processes your write in the background.

### Index builder

The index builder stores your write data in an in-memory structure called a memtable. This includes your vector data, any metadata you've attached, and the sequence number. If you're updating or deleting a record, the system also tracks how to handle the old version during queries.

Periodically, the index builder moves data from the memtable to permanent storage. In [object storage](#object-storage), your data is organized into immutable files called slabs. These slabs are optimized for query performance. Smaller slabs use fast indexing techniques that provide good performance with minimal resource requirements. As slabs grow, the system merges them into larger slabs that use more sophisticated methods that provide better performance at scale. This adaptive process both optimizes query performance for each slab and amortizes the cost of more expensive indexing through the lifetime of the namespace.

<Note>
  All read operations check the memtable first, so you can immediately search data that you've just written, even before it's moved to permanent storage. For more details, see [Query executors](#query-executors).
</Note>

## Read path

<img />

<img />

### Query routers

When you send a search query, the [data plane](#data-plane) first validates your request and checks that it meets system limits like [rate and object limits](/reference/api/database-limits). The query router then identifies which slabs contain relevant data and routes your query to the appropriate executors. It also searches the memtable for any recent data that hasn't been moved to permanent storage yet.

### Query executors

Each query executor searches through its assigned slabs and returns the most relevant candidates to the query router. If your query includes metadata filters, the executors exclude records that don't match your criteria before finding the best matches.

Most of the time, the slabs are cached in memory or on local SSD, which provides very fast query performance. If a slab isn't cached (which happens when it's accessed for the first time or hasn't been used recently), the executor fetches it from object storage and caches it for future queries.

The query router then combines results from all executors, removes duplicates, merges them with results from the memtable, and returns the final set of best matches to you.


# Pinecone documentation
Source: https://docs.pinecone.io/guides/get-started/overview

Pinecone is the vector database for AI agents and applications, built for semantic search, knowledge retrieval, and long-term memory at scale.

## Get started

<CardGroup>
  <Card title="Database quickstart" icon="database" href="/guides/get-started/quickstart">
    Build semantic search and knowledge retrieval into your agent or app
  </Card>

  <Card title="Assistant quickstart" icon="comments" href="/guides/assistant/quickstart/sdk-quickstart">
    Create an AI assistant that answers questions about your proprietary data
  </Card>

  <Card title="Nexus quickstart" icon="brain-circuit" href="/guides/nexus/quickstart">
    Compile your data into a context and query it for grounded, cited answers
  </Card>

  <Card title="Marketplace quickstart" icon="store" href="/guides/marketplace/quickstart">
    Publish a no-code knowledge app from a template (public preview)
  </Card>
</CardGroup>

## Build

<CardGroup>
  <Card title="IDEs & CLIs" icon="wand-magic-sparkles" href="/guides/get-started/ai-coding-tools">
    Use Pinecone with Claude Code, Gemini CLI, Cursor, and other agentic tools
  </Card>

  <Card title="MCP server" icon="server" href="/guides/operations/mcp-server">
    Connect any MCP-compatible agent to Pinecone for search and index management
  </Card>

  <Card title="API reference" icon="code-simple" href="/reference">
    Comprehensive details about the Pinecone APIs, SDKs, and architecture
  </Card>

  <Card title="Examples" icon="grid-round" href="/examples">
    Notebooks and sample apps with common AI patterns
  </Card>

  <Card title="Integrations" icon="link-simple" href="/integrations/overview">
    Third-party integrations for LangChain, LlamaIndex, and more
  </Card>

  <Card title="Releases" icon="party-horn" href="/release-notes">
    What's new in Pinecone
  </Card>
</CardGroup>


# Quickstart
Source: https://docs.pinecone.io/guides/get-started/quickstart

Add Pinecone to your AI agent or app in minutes. Build a knowledge retrieval agent, use your IDE assistant, or integrate the SDK directly.

Get Pinecone running in your agent or app. Install the Pinecone plugin for your AI coding tool to get started instantly, or follow a step-by-step path below.

## Agent / LLM? Start here

If you're an AI agent or LLM reading this page to generate Pinecone code, here's the full working pattern as a single runnable script.

```python theme={null}
import time
from pinecone import Pinecone

pc = Pinecone(api_key="{{YOUR_API_KEY}}")

# Use create_index_for_model, not the dimension-based create_index
if not pc.has_index("quickstart"):
    pc.create_index_for_model(
        name="quickstart",
        cloud="aws",
        region="us-east-1",
        embed={
            "model": "llama-text-embed-v2",
            "field_map": {"text": "content"}
        }
    )

index = pc.Index("quickstart")

# Use upsert_records, not upsert(); keyword args required in SDK v9+; each record needs _id + the field_map field
index.upsert_records(
    namespace="docs",
    records=[
        {"_id": "rec1", "content": "Refund requests must be submitted within 30 days.", "category": "policy"},
        {"_id": "rec2", "content": "Enterprise support responds within 4 hours.", "category": "policy"},
        {"_id": "rec3", "content": "New employees receive 15 days PTO in year one.", "category": "hr"},
        {"_id": "rec4", "content": "Production deployments require team lead approval.", "category": "ops"},
        {"_id": "rec5", "content": "API rate limit: 1000 requests/minute on Pro tier.", "category": "specs"},
    ]
)

time.sleep(5)  # records take a few seconds to become searchable

# Use search() with inputs, not query() with vector=
results = index.search(
    namespace="docs",
    query={"top_k": 5, "inputs": {"text": "what is the refund policy"}},
    rerank={
        "model": "bge-reranker-v2-m3",
        "top_n": 3,
        "rank_fields": ["content"]
    }
)

for hit in results["result"]["hits"]:
    print(f"{hit.score:.2f}  {hit.fields['content']}")
```

***

## Get set up

To get started, you'll need a Pinecone account and API key.

### 1. Create a Pinecone account

If you're new to Pinecone, sign up at [app.pinecone.io](https://app.pinecone.io) and choose a plan:

* [Starter plan](https://pinecone.io/pricing/) (free): Free access to most features, but you're limited to one cloud region and need to stay under Starter plan [limits](/reference/api/database-limits).

* [Builder plan](https://pinecone.io/pricing/) (\$20/month): Higher quotas than Starter and predictable flat pricing with no usage overages, plus the ability to create indexes in any supported cloud region. Ideal for small production apps.

* [Standard plan trial](/guides/organizations/manage-billing/standard-trial): 21 days and \$300 in credits with access to Standard plan [features](https://www.pinecone.io/pricing/) and [higher limits](/reference/api/database-limits) that let you test Pinecone at scale.

<Note>
  If you're already on a Starter plan, you can [upgrade to Builder](/guides/organizations/manage-billing/upgrade-billing-plan) at any time, or activate a Standard plan trial (one trial per organization).
</Note>

After signing up, you'll receive an API key in the console. Save this key. You'll need it to authenticate your requests to Pinecone.

### 2. Get a Pinecone API key

Create a new API key in the [Pinecone console](https://app.pinecone.io/organizations/-/keys), or use the widget below to generate a key. If you don't have a Pinecone account, the widget will sign you up for the free [Starter plan](https://www.pinecone.io/pricing/).

<div>
  <div>
    <div>
      <div />
    </div>
  </div>
</div>

Your generated API key:

```shell theme={null}
"{{YOUR_API_KEY}}"
```

## Fastest: use your AI coding tool

Install the Pinecone plugin for your AI coding tool, then run the quickstart command. The plugin gives your agent up-to-date Pinecone API references, skills, and a bundled MCP server. The quickstart command walks you through setup with the official [Pinecone CLI](/reference/cli/quickstart) before generating and running sample code, so you end up with a reproducible setup instead of pasted snippets.

<Tabs>
  <Tab title="Claude Code">
    Set your API key, then install the [Pinecone plugin for Claude Code](/integrations/claude-code):

    ```shell theme={null}
    export PINECONE_API_KEY="{{YOUR_API_KEY}}"
    claude plugin install pinecone
    ```

    Start Claude Code and run the quickstart command:

    ```text theme={null}
    /pinecone:quickstart
    ```

    The plugin also includes other slash commands, such as `/pinecone:query`, for interactively querying your indexes.
  </Tab>

  <Tab title="Cursor">
    Add your Pinecone API key to a `.env` file at your workspace root:

    ```text theme={null}
    PINECONE_API_KEY={{YOUR_API_KEY}}
    ```

    Install the [Pinecone plugin for Cursor](/integrations/cursor) from the [Cursor Marketplace](https://cursor.com/marketplace/pinecone), or in Cursor chat run:

    ```text theme={null}
    /add-plugin pinecone
    ```

    Then run the quickstart command in Cursor Agent chat:

    ```text theme={null}
    /pinecone-quickstart
    ```
  </Tab>

  <Tab title="Other IDEs">
    Install [Pinecone Agent Skills](/integrations/agent-skills), then ask your agent to get started:

    ```bash theme={null}
    npx skills add pinecone-io/skills
    ```

    ```text theme={null}
    Help me get started with Pinecone. Create a serverless index with
    integrated embedding, upsert some sample data, and run a search.
    ```
  </Tab>
</Tabs>

<Tip>
  To drive the same setup yourself without an AI tool, use the [Pinecone CLI](/reference/cli/quickstart) directly. For full MCP server setup (index management, search, and docs access from your IDE), see [Use the Pinecone MCP server](/guides/operations/mcp-server).
</Tip>

## Choose your path

<Note>
  **Records or documents?** There are two ways to model data in Pinecone, and the choice is made when you create the index. An index created with a dense or sparse vector type holds [records](/guides/get-started/concepts#record), the path the steps below follow using integrated embedding (`create_index_for_model` + `upsert_records` + `search`). An index created with a document schema holds [documents](/guides/get-started/concepts#document) and supports [full-text search](/guides/search/full-text-search) with BM25 ranking and Lucene queries (public preview, with REST and Python SDK support). If keyword and phrase matching matters to your search, or you need more than one ranking signal in a single index, start from [full-text search](/guides/search/full-text-search) instead. To compare the two models, see [Data modeling](/guides/index-data/data-modeling).
</Note>

<CardGroup>
  <Card title="Agent" icon="robot" href="#build-a-knowledge-retrieval-agent">
    Build a knowledge retrieval agent with Pinecone as a tool. \~80 lines of Python.
  </Card>

  <Card title="IDE assistant" icon="wand-magic-sparkles" href="#fastest-use-your-ai-coding-tool">
    Let Claude Code, Cursor, or Gemini CLI build it for you.
  </Card>

  <Card title="SDK" icon="code" href="#integrate-the-sdk-directly">
    Integrate Pinecone directly with Python, JavaScript, Java, or Go.
  </Card>

  <Card title="No-code" icon="diagram-project" href="#no-code-with-n8n">
    Build a workflow in n8n without writing code.
  </Card>
</CardGroup>

***

## Build a knowledge retrieval agent

Build an AI agent that uses Pinecone to retrieve knowledge and answer questions accurately. This demo shows Pinecone as a tool inside an agent, which is the same pattern you'd use in production.

<Note>
  This path requires an [Anthropic](https://console.anthropic.com/) or [OpenAI](https://platform.openai.com/api-keys) API key alongside your Pinecone API key. If you don't have one, try the [IDE assistant](#fastest-use-your-ai-coding-tool) or [SDK](#integrate-the-sdk-directly) path instead.
</Note>

<Steps>
  <Step title="Install dependencies">
    <CodeGroup>
      ```bash Anthropic (Claude) theme={null}
      pip install pinecone anthropic
      ```

      ```bash OpenAI theme={null}
      pip install pinecone openai
      ```
    </CodeGroup>
  </Step>

  <Step title="Create an index and load knowledge">
    Create a Pinecone index with [integrated embedding](/guides/index-data/indexing-overview#integrated-embedding) and load a small knowledge base. These are facts your LLM doesn't know on its own, so retrieval is the only way to answer accurately.

    <CodeGroup>
      ```python Anthropic (Claude) theme={null}
      import anthropic
      from pinecone import Pinecone

      pc = Pinecone(api_key="{{YOUR_API_KEY}}")
      llm = anthropic.Anthropic(api_key="YOUR_ANTHROPIC_API_KEY")

      # Create an index with integrated embedding
      if not pc.has_index("knowledge"):
          pc.create_index_for_model(
              name="knowledge",
              cloud="aws",
              region="us-east-1",
              embed={
                  "model": "llama-text-embed-v2",
                  "field_map": {"text": "content"}
              }
          )

      index = pc.Index("knowledge")

      # Load your knowledge base
      index.upsert_records(
          namespace="docs",
          records=[
              {"_id": "policy-1", "content": "Refund requests must be submitted within 30 days of purchase. After 30 days, only store credit is available.", "category": "policies"},
              {"_id": "policy-2", "content": "Enterprise customers get dedicated support with a 4-hour response time SLA. Standard support responds within 24 hours.", "category": "policies"},
              {"_id": "spec-1", "content": "The WonderVector 5000 supports up to 100,000 vectors per namespace with a maximum dimensionality of 4096.", "category": "specs"},
              {"_id": "spec-2", "content": "API rate limits: Free tier is 100 requests/minute, Pro tier is 1000 requests/minute, Enterprise is unlimited with fair use.", "category": "specs"},
              {"_id": "spec-3", "content": "Data is encrypted at rest using AES-256 and in transit using TLS 1.3. SOC2 Type II compliance is maintained.", "category": "security"},
              {"_id": "hr-1", "content": "New employees receive 15 days PTO in their first year, increasing to 20 days after 2 years and 25 days after 5 years.", "category": "hr"},
              {"_id": "hr-2", "content": "The company matches 401k contributions up to 4% of salary. Vesting is immediate for all employees.", "category": "hr"},
              {"_id": "proc-1", "content": "To request a new software license, submit a ticket in the IT portal. Approvals take 2-3 business days for standard software.", "category": "procedures"},
              {"_id": "proc-2", "content": "Production deployments require approval from the team lead and a passing CI/CD pipeline. Hotfixes can bypass the lead approval.", "category": "procedures"},
              {"_id": "proc-3", "content": "Vendor invoices over $10,000 require VP approval. Under $10,000 requires manager approval only.", "category": "procedures"},
          ]
      )
      ```

      ```python OpenAI theme={null}
      from openai import OpenAI
      from pinecone import Pinecone

      pc = Pinecone(api_key="{{YOUR_API_KEY}}")
      llm = OpenAI(api_key="YOUR_OPENAI_API_KEY")

      # Create an index with integrated embedding
      if not pc.has_index("knowledge"):
          pc.create_index_for_model(
              name="knowledge",
              cloud="aws",
              region="us-east-1",
              embed={
                  "model": "llama-text-embed-v2",
                  "field_map": {"text": "content"}
              }
          )

      index = pc.Index("knowledge")

      # Load your knowledge base
      index.upsert_records(
          namespace="docs",
          records=[
              {"_id": "policy-1", "content": "Refund requests must be submitted within 30 days of purchase. After 30 days, only store credit is available.", "category": "policies"},
              {"_id": "policy-2", "content": "Enterprise customers get dedicated support with a 4-hour response time SLA. Standard support responds within 24 hours.", "category": "policies"},
              {"_id": "spec-1", "content": "The WonderVector 5000 supports up to 100,000 vectors per namespace with a maximum dimensionality of 4096.", "category": "specs"},
              {"_id": "spec-2", "content": "API rate limits: Free tier is 100 requests/minute, Pro tier is 1000 requests/minute, Enterprise is unlimited with fair use.", "category": "specs"},
              {"_id": "spec-3", "content": "Data is encrypted at rest using AES-256 and in transit using TLS 1.3. SOC2 Type II compliance is maintained.", "category": "security"},
              {"_id": "hr-1", "content": "New employees receive 15 days PTO in their first year, increasing to 20 days after 2 years and 25 days after 5 years.", "category": "hr"},
              {"_id": "hr-2", "content": "The company matches 401k contributions up to 4% of salary. Vesting is immediate for all employees.", "category": "hr"},
              {"_id": "proc-1", "content": "To request a new software license, submit a ticket in the IT portal. Approvals take 2-3 business days for standard software.", "category": "procedures"},
              {"_id": "proc-2", "content": "Production deployments require approval from the team lead and a passing CI/CD pipeline. Hotfixes can bypass the lead approval.", "category": "procedures"},
              {"_id": "proc-3", "content": "Vendor invoices over $10,000 require VP approval. Under $10,000 requires manager approval only.", "category": "procedures"},
          ]
      )
      ```
    </CodeGroup>

    <Note>
      Pinecone is eventually consistent. New records may take a few seconds to become searchable.
    </Note>
  </Step>

  <Step title="Define Pinecone as a tool">
    Wrap Pinecone search in a function your agent can call. Drop this into any agent codebase to add knowledge retrieval. Run all snippets in the same Python session so `index` and `llm` stay in scope.

    <div>
      **Agent tool: `search_knowledge_base`**

      ```python Python theme={null}
      def search_knowledge_base(query: str) -> str:
          """Search the knowledge base for relevant information."""
          results = index.search(
              namespace="docs",
              # To scope by metadata, add "filter": {"category": {"$eq": "policies"}} to the query dict
              query={"top_k": 3, "inputs": {"text": query}},
              rerank={
                  "model": "bge-reranker-v2-m3",
                  "top_n": 3,
                  "rank_fields": ["content"]
              }
          )
          return "\n\n".join(
              hit.fields["content"]
              for hit in results["result"]["hits"]
          )
      ```
    </div>
  </Step>

  <Step title="Wire the tool into your agent">
    Give your LLM the ability to call the search function when it needs information.

    <CodeGroup>
      ```python Anthropic (Claude) theme={null}
      tools = [{
          "name": "search_knowledge_base",
          "description": "Search the company knowledge base for policies, specs, HR info, and procedures.",
          "input_schema": {
              "type": "object",
              "properties": {
                  "query": {"type": "string", "description": "The search query"}
              },
              "required": ["query"]
          }
      }]

      def ask(question: str) -> str:
          messages = [{"role": "user", "content": question}]

          # disable_parallel_tool_use keeps this loop simple: with parallel calls,
          # every tool_use block would need a matching tool_result in the next message
          response = llm.messages.create(
              model="claude-sonnet-4-5",
              max_tokens=1024,
              tools=tools,
              tool_choice={"type": "auto", "disable_parallel_tool_use": True},
              messages=messages
          )

          # If the model wants to use a tool, call it and return the result
          while response.stop_reason == "tool_use":
              tool_block = next(b for b in response.content if b.type == "tool_use")
              tool_result = search_knowledge_base(tool_block.input["query"])

              messages += [
                  {"role": "assistant", "content": response.content},
                  {"role": "user", "content": [{
                      "type": "tool_result",
                      "tool_use_id": tool_block.id,
                      "content": tool_result
                  }]}
              ]

              response = llm.messages.create(
                  model="claude-sonnet-4-5",
                  max_tokens=1024,
                  tools=tools,
                  tool_choice={"type": "auto", "disable_parallel_tool_use": True},
                  messages=messages
              )

          return next(b.text for b in response.content if hasattr(b, "text"))
      ```

      ```python OpenAI theme={null}
      import json

      tools = [{
          "type": "function",
          "function": {
              "name": "search_knowledge_base",
              "description": "Search the company knowledge base for policies, specs, HR info, and procedures.",
              "parameters": {
                  "type": "object",
                  "properties": {
                      "query": {"type": "string", "description": "The search query"}
                  },
                  "required": ["query"]
              }
          }
      }]

      def ask(question: str) -> str:
          messages = [{"role": "user", "content": question}]

          # parallel_tool_calls=False keeps this loop simple: with parallel calls,
          # every tool call would need a matching tool message in the next turn
          response = llm.chat.completions.create(
              model="gpt-4o",
              tools=tools,
              parallel_tool_calls=False,
              messages=messages
          )

          # If the model wants to use a tool, call it and return the result
          while response.choices[0].finish_reason == "tool_calls":
              tool_call = response.choices[0].message.tool_calls[0]
              args = json.loads(tool_call.function.arguments)
              tool_result = search_knowledge_base(args["query"])

              messages += [
                  response.choices[0].message,
                  {"role": "tool", "tool_call_id": tool_call.id, "content": tool_result}
              ]

              response = llm.chat.completions.create(
                  model="gpt-4o",
                  tools=tools,
                  parallel_tool_calls=False,
                  messages=messages
              )

          return response.choices[0].message.content
      ```
    </CodeGroup>
  </Step>

  <Step title="Ask your agent a question">
    ```python theme={null}
    print(ask("What's the refund policy?"))
    ```

    If the agent says it can't find the information, wait a few seconds and retry. Pinecone is eventually consistent, so freshly upserted records take a moment to become searchable.

    Your agent searches Pinecone, retrieves the relevant policy, and answers:

    ```console Output theme={null}
    Refund requests must be submitted within 30 days of purchase. After that
    30-day window, you can still receive store credit but not a direct refund.
    ```

    Try a few more questions:

    ```python theme={null}
    print(ask("How much PTO do new employees get?"))
    print(ask("What approval do I need for a $15,000 vendor invoice?"))
    ```
  </Step>
</Steps>

<Note>
  **What just happened:** Your LLM received a question, decided it needed more information, and called the `search_knowledge_base` tool. Pinecone returned the most relevant records with reranking, and the LLM synthesized an accurate answer from the retrieved context. Production RAG agents use this same pattern, and the `search_knowledge_base` function works in any agent framework.
</Note>

### Next steps

<CardGroup>
  <Card title="Build a RAG chatbot" icon="comments" href="/guides/get-started/build-a-rag-chatbot">
    Add conversation history, streaming, and a web UI
  </Card>

  <Card title="Search methods" icon="magnifying-glass" href="/guides/search/search-overview">
    Explore semantic, hybrid, and full-text search
  </Card>

  <Card title="Data modeling" icon="table" href="/guides/index-data/data-modeling">
    Model your data for efficient retrieval
  </Card>
</CardGroup>

***

## Integrate the SDK directly

Integrate Pinecone directly into your application. Use these SDK calls wherever your code needs knowledge retrieval, whether that's an agent, a backend service, or a standalone script.

<Tip>
  To get started in your browser, use the [Quickstart colab notebook](https://colab.research.google.com/github/pinecone-io/examples/blob/master/docs/pinecone-quickstart.ipynb).
</Tip>

### 1. Install an SDK

<CodeGroup>
  ```shell Python theme={null}
  pip install pinecone
  ```

  ```shell JavaScript theme={null}
  npm install @pinecone-database/pinecone
  ```

  ```shell Java theme={null}
  # Maven
  <dependency>
    <groupId>io.pinecone</groupId>
    <artifactId>pinecone-client</artifactId>
    <version>5.0.0</version>
  </dependency>

  # Gradle
  implementation "io.pinecone:pinecone-client:5.0.0"
  ```

  ```shell Go theme={null}
  go get github.com/pinecone-io/go-pinecone/v4/pinecone
  ```
</CodeGroup>

### 2. Create an index

Create an [index with integrated embedding](/guides/index-data/create-an-index#create-an-index-for-dense-vectors) so you can upsert and search with text. Pinecone generates the vectors for you.

<Note>
  If you prefer to use external embedding models, see [Bring your own vectors](/guides/index-data/indexing-overview#bring-your-own-vectors).
</Note>

```python Python theme={null}
from pinecone import Pinecone

pc = Pinecone(api_key="{{YOUR_API_KEY}}")

index_name = "quickstart-py"
if not pc.has_index(index_name):
    pc.create_index_for_model(
        name=index_name,
        cloud="aws",
        region="us-east-1",
        embed={
            "model":"llama-text-embed-v2",
            "field_map":{"text": "chunk_text"}
        }
    )
```

<Accordion title="JavaScript, Java, and Go">
  <CodeGroup>
    ```javascript JavaScript theme={null}
    import { Pinecone } from '@pinecone-database/pinecone'

    const pc = new Pinecone({ apiKey: '{{YOUR_API_KEY}}' });

    const indexName = 'quickstart-js';
    await pc.createIndexForModel({
      name: indexName,
      cloud: 'aws',
      region: 'us-east-1',
      embed: {
        model: 'llama-text-embed-v2',
        fieldMap: { text: 'chunk_text' },
      },
      waitUntilReady: true,
    });
    ```

    ```java Java theme={null}
    import io.pinecone.clients.Index;
    import io.pinecone.clients.Pinecone;
    import org.openapitools.db_control.client.ApiException;
    import org.openapitools.db_control.client.model.CreateIndexForModelRequest;
    import org.openapitools.db_control.client.model.CreateIndexForModelRequestEmbed;
    import org.openapitools.db_control.client.model.DeletionProtection;
    import org.openapitools.db_control.client.model.IndexModel;
    import org.openapitools.db_data.client.model.SearchRecordsRequestQuery;
    import org.openapitools.db_data.client.model.SearchRecordsResponse;
    import io.pinecone.proto.DescribeIndexStatsResponse;

    import java.util.*;

    public class Quickstart {
        public static void main(String[] args) throws ApiException {
            Pinecone pc = new Pinecone.Builder("{{YOUR_API_KEY}}").build();
            String indexName = "quickstart-java";
            String region = "us-east-1";
            HashMap<String, String> fieldMap = new HashMap<>();
            fieldMap.put("text", "chunk_text");
            CreateIndexForModelRequestEmbed embed = new CreateIndexForModelRequestEmbed()
                    .model("llama-text-embed-v2")
                    .fieldMap(fieldMap);
            IndexModel index = pc.createIndexForModel(
                    indexName,
                    CreateIndexForModelRequest.CloudEnum.AWS,
                    region,
                    embed,
                    DeletionProtection.DISABLED,
                    null
            );
        }
    }
    ```

    ```go Go theme={null}
    package main

    import (
        "context"
        "encoding/json"
        "fmt"
        "log"

        "github.com/pinecone-io/go-pinecone/v4/pinecone"
    )

    func main() {
        ctx := context.Background()

        pc, err := pinecone.NewClient(pinecone.NewClientParams{
            ApiKey: "{{YOUR_API_KEY}}",
        })
        if err != nil {
            log.Fatalf("Failed to create Client: %v", err)
        }

      	indexName := "quickstart-go"
        index, err := pc.CreateIndexForModel(ctx, &pinecone.CreateIndexForModelRequest{
            Name:   indexName,
            Cloud:  pinecone.Aws,
            Region: "us-east-1",
            Embed: pinecone.CreateIndexForModelEmbed{
                Model:    "llama-text-embed-v2",
                FieldMap: map[string]interface{}{"text": "chunk_text"},
            },
        })
        if err != nil {
            log.Fatalf("Failed to create serverless index: %v", err)
        } else {
            fmt.Printf("Successfully created serverless index: %v", index.Name)
        }
    }

    func prettifyStruct(obj interface{}) string {
      	bytes, _ := json.MarshalIndent(obj, "", "  ")
        return string(bytes)
    }
    ```
  </CodeGroup>
</Accordion>

### 3. Upsert data

Load records into your index. Each record has an ID, text content, and optional metadata. Pinecone converts the text to vectors automatically using the integrated embedding model.

```python Python [expandable] theme={null}
index = pc.Index(index_name)

index.upsert_records(
    namespace="example-namespace",
    records=[
        {"_id": "rec1", "chunk_text": "The Eiffel Tower was completed in 1889 and stands in Paris, France.", "category": "history"},
        {"_id": "rec2", "chunk_text": "Photosynthesis allows plants to convert sunlight into energy.", "category": "science"},
        {"_id": "rec3", "chunk_text": "Albert Einstein developed the theory of relativity.", "category": "science"},
        {"_id": "rec4", "chunk_text": "The mitochondrion is often called the powerhouse of the cell.", "category": "biology"},
        {"_id": "rec5", "chunk_text": "Shakespeare wrote many famous plays, including Hamlet and Macbeth.", "category": "literature"},
        {"_id": "rec6", "chunk_text": "The Great Wall of China was built to protect against invasions.", "category": "history"},
        {"_id": "rec7", "chunk_text": "The Pyramids of Giza are among the Seven Wonders of the Ancient World.", "category": "history"},
        {"_id": "rec8", "chunk_text": "Leonardo da Vinci painted the Mona Lisa.", "category": "art"},
        {"_id": "rec9", "chunk_text": "The internet revolutionized communication and information sharing.", "category": "technology"},
        {"_id": "rec10", "chunk_text": "Renewable energy sources include wind, solar, and hydroelectric power.", "category": "energy"},
    ]
)
```

<Accordion title="JavaScript, Java, and Go">
  <CodeGroup>
    ```javascript JavaScript [expandable] theme={null}
    const namespace = pc.index(indexName).namespace("example-namespace");

    await namespace.upsertRecords({ records: [
      {"_id": "rec1", "chunk_text": "The Eiffel Tower was completed in 1889 and stands in Paris, France.", "category": "history"},
      {"_id": "rec2", "chunk_text": "Photosynthesis allows plants to convert sunlight into energy.", "category": "science"},
      {"_id": "rec3", "chunk_text": "Albert Einstein developed the theory of relativity.", "category": "science"},
      {"_id": "rec4", "chunk_text": "The mitochondrion is often called the powerhouse of the cell.", "category": "biology"},
      {"_id": "rec5", "chunk_text": "Shakespeare wrote many famous plays, including Hamlet and Macbeth.", "category": "literature"},
      {"_id": "rec6", "chunk_text": "The Great Wall of China was built to protect against invasions.", "category": "history"},
      {"_id": "rec7", "chunk_text": "The Pyramids of Giza are among the Seven Wonders of the Ancient World.", "category": "history"},
      {"_id": "rec8", "chunk_text": "Leonardo da Vinci painted the Mona Lisa.", "category": "art"},
      {"_id": "rec9", "chunk_text": "The internet revolutionized communication and information sharing.", "category": "technology"},
      {"_id": "rec10", "chunk_text": "Renewable energy sources include wind, solar, and hydroelectric power.", "category": "energy"},
    ] });
    ```

    ```java Java [expandable] theme={null}
    // Add to the Quickstart class:
    Index index = pc.getIndexConnection(indexName);

    ArrayList<Map<String, String>> upsertRecords = new ArrayList<>();
    String[][] data = {
        {"rec1", "The Eiffel Tower was completed in 1889 and stands in Paris, France.", "history"},
        {"rec2", "Photosynthesis allows plants to convert sunlight into energy.", "science"},
        {"rec3", "Albert Einstein developed the theory of relativity.", "science"},
        {"rec4", "The mitochondrion is often called the powerhouse of the cell.", "biology"},
        {"rec5", "Shakespeare wrote many famous plays, including Hamlet and Macbeth.", "literature"},
        {"rec6", "The Great Wall of China was built to protect against invasions.", "history"},
        {"rec7", "The Pyramids of Giza are among the Seven Wonders of the Ancient World.", "history"},
        {"rec8", "Leonardo da Vinci painted the Mona Lisa.", "art"},
        {"rec9", "The internet revolutionized communication and information sharing.", "technology"},
        {"rec10", "Renewable energy sources include wind, solar, and hydroelectric power.", "energy"},
    };
    for (String[] row : data) {
        HashMap<String, String> record = new HashMap<>();
        record.put("_id", row[0]);
        record.put("chunk_text", row[1]);
        record.put("category", row[2]);
        upsertRecords.add(record);
    }
    index.upsertRecords("example-namespace", upsertRecords);
    ```

    ```go Go [expandable] theme={null}
    // Add to the main function:
    idxConnection, err := pc.IndexFromName(ctx, indexName)
    if err != nil {
        log.Fatalf("Failed to get index connection: %v", err)
    }

    records := []pinecone.UpsertRecord{
        {Id: "rec1", Fields: map[string]interface{}{"chunk_text": "The Eiffel Tower was completed in 1889 and stands in Paris, France.", "category": "history"}},
        {Id: "rec2", Fields: map[string]interface{}{"chunk_text": "Photosynthesis allows plants to convert sunlight into energy.", "category": "science"}},
        {Id: "rec3", Fields: map[string]interface{}{"chunk_text": "Albert Einstein developed the theory of relativity.", "category": "science"}},
        {Id: "rec4", Fields: map[string]interface{}{"chunk_text": "The mitochondrion is often called the powerhouse of the cell.", "category": "biology"}},
        {Id: "rec5", Fields: map[string]interface{}{"chunk_text": "Shakespeare wrote many famous plays, including Hamlet and Macbeth.", "category": "literature"}},
        {Id: "rec6", Fields: map[string]interface{}{"chunk_text": "The Great Wall of China was built to protect against invasions.", "category": "history"}},
        {Id: "rec7", Fields: map[string]interface{}{"chunk_text": "The Pyramids of Giza are among the Seven Wonders of the Ancient World.", "category": "history"}},
        {Id: "rec8", Fields: map[string]interface{}{"chunk_text": "Leonardo da Vinci painted the Mona Lisa.", "category": "art"}},
        {Id: "rec9", Fields: map[string]interface{}{"chunk_text": "The internet revolutionized communication and information sharing.", "category": "technology"}},
        {Id: "rec10", Fields: map[string]interface{}{"chunk_text": "Renewable energy sources include wind, solar, and hydroelectric power.", "category": "energy"}},
    }
    err = idxConnection.UpsertRecords(ctx, "example-namespace", records)
    if err != nil {
        log.Fatalf("Failed to upsert records: %v", err)
    }
    ```
  </CodeGroup>
</Accordion>

<Note>
  Pinecone is eventually consistent. New records may take a few seconds to become searchable.
</Note>

### 4. Search and rerank

Search the index for records semantically similar to a query, then [rerank](/guides/search/rerank-results) for more accurate results.

```python Python theme={null}
query = "Famous historical structures and monuments"

results = index.search(
    namespace="example-namespace",
    query={
        "top_k": 10,
        "inputs": {"text": query}
    },
    rerank={
        "model": "bge-reranker-v2-m3",
        "top_n": 5,
        "rank_fields": ["chunk_text"]
    }
)

for hit in results["result"]["hits"]:
    print(f"score: {round(hit.score, 2):<5} | {hit.fields['chunk_text']}")
```

```console Output theme={null}
score: 0.11  | The Eiffel Tower was completed in 1889 and stands in Paris, France.
score: 0.06  | The Great Wall of China was built to protect against invasions.
score: 0.02  | The Pyramids of Giza are among the Seven Wonders of the Ancient World.
score: 0.01  | Leonardo da Vinci painted the Mona Lisa.
score: 0.0   | Shakespeare wrote many famous plays, including Hamlet and Macbeth.
```

<Accordion title="JavaScript, Java, and Go">
  <CodeGroup>
    ```javascript JavaScript theme={null}
    const query = 'Famous historical structures and monuments';

    const results = await namespace.searchRecords({
      query: {
        topK: 10,
        inputs: { text: query },
      },
      rerank: {
        model: 'bge-reranker-v2-m3',
        topN: 5,
        rankFields: ['chunk_text'],
      },
    });

    results.result.hits.forEach(hit => {
      console.log(`score: ${hit._score.toFixed(2)}, text: ${hit.fields.chunk_text}`);
    });
    ```

    ```java Java theme={null}
    // Add to the Quickstart class:
    String query = "Famous historical structures and monuments";
    List<String> fields = new ArrayList<>();
    fields.add("category");
    fields.add("chunk_text");

    List<String> rankFields = new ArrayList<>();
    rankFields.add("chunk_text");
    SearchRecordsRequestRerank rerank = new SearchRecordsRequestRerank()
            .query(query)
            .model("bge-reranker-v2-m3")
            .topN(5)
            .rankFields(rankFields);

    SearchRecordsResponse response = index.searchRecordsByText(
        query, "example-namespace", fields, 10, null, rerank
    );
    System.out.println(response);
    ```

    ```go Go theme={null}
    // Add to the main function:
    query := "Famous historical structures and monuments"
    topN := int32(5)

    res, err := idxConnection.SearchRecords(ctx, &pinecone.SearchRecordsRequest{
        Query: pinecone.SearchRecordsQuery{
            TopK: 10,
            Inputs: &map[string]interface{}{
                "text": query,
            },
        },
        Rerank: &pinecone.SearchRecordsRerank{
            Model:      "bge-reranker-v2-m3",
            TopN:       &topN,
            RankFields: []string{"chunk_text"},
        },
    })
    if err != nil {
        log.Fatalf("Failed to search records: %v", err)
    }
    fmt.Printf(prettifyStruct(res))
    ```
  </CodeGroup>
</Accordion>

### 5. Clean up

When you no longer need the example index, delete it:

```python Python theme={null}
pc.delete_index(index_name)
```

<Accordion title="JavaScript, Java, and Go">
  <CodeGroup>
    ```javascript JavaScript theme={null}
    await pc.deleteIndex(indexName);
    ```

    ```java Java theme={null}
    pc.deleteIndex(indexName);
    ```

    ```go Go theme={null}
    err = pc.DeleteIndex(ctx, indexName)
    if err != nil {
        log.Fatalf("Failed to delete index: %v", err)
    }
    ```
  </CodeGroup>
</Accordion>

<Tip>
  For production indexes, consider [enabling deletion protection](/guides/manage-data/manage-indexes#configure-deletion-protection).
</Tip>

### Next steps

<CardGroup>
  <Card title="Index data" icon="book-open" href="/guides/index-data/indexing-overview">
    Learn more about storing data in Pinecone
  </Card>

  <Card title="Search" icon="magnifying-glass" href="/guides/search/search-overview">
    Explore different forms of vector search
  </Card>

  <Card title="Optimize" icon="rocket" href="/guides/optimize">
    Find out how to improve performance
  </Card>
</CardGroup>

***

## No-code with n8n

Create an AI workflow that uses Pinecone for knowledge retrieval without writing any code.

Use [n8n](https://docs.n8n.io/choose-n8n/) to create a workflow that downloads files via HTTP and lets you chat with them using Pinecone Database and OpenAI.

<Tip>
  If you're not interested in chunking and embedding your own data, [use n8n with Pinecone Assistant](/guides/assistant/quickstart/n8n-quickstart) instead.
</Tip>

### 1. Get an OpenAI API key

Create a new API key in the [OpenAI console](https://platform.openai.com/api-keys).

### 2. Create an index

[Create an index](https://app.pinecone.io/organizations/-/projects/-/create-index/serverless) in the Pinecone console:

* Name your index `n8n-dense-index`
* Under **Configuration**, check **Custom settings** and set **Dimension** to 1536.
* Leave everything else as default.

### 3. Set up n8n

<Steps>
  <Step title="Create a new workflow">
    In your n8n account, [create a new workflow](https://docs.n8n.io/workflows/create/).
  </Step>

  <Step title="Import a workflow template">
    Copy this workflow template URL:

    ```shell theme={null}
    https://raw.githubusercontent.com/pinecone-io/n8n-templates/refs/heads/main/database-quickstart/database-quickstart.json
    ```

    Paste the URL into the workflow editor and then click **Import** to add the workflow.
  </Step>

  <Step title="Add credentials to the workflow">
    * Add your Pinecone credentials:
      * In the **Pinecone Vector Store** node, select **Credential to connect with** > **Create new credential** and paste in your Pinecone API key.
      * Name the credential **Pinecone** so that other nodes reference it.

    * Add your OpenAI credentials:
      * In the **OpenAI Chat Model**, select **Credential to connect with** > **Create new credential** and paste in your OpenAI API key.
  </Step>

  <Step title="Activate the workflow">
    The workflow is configured to download recent Pinecone release notes and upload them to your Pinecone index. Click **Execute workflow** to start the workflow.

    <Tip>
      You can add your own files to the workflow by changing the URLs in the **Set file urls** node.
    </Tip>
  </Step>
</Steps>

### 4. Chat with your docs

Once the workflow is activated, ask it for the latest changes to Pinecone Database:

```
What's new in Pinecone Database?
```

### Next steps

* Use your own data:
  * Change the urls in **Set file urls** node to use your own files.
  * You may need to adjust the chunk sizes in the **Recursive Character Text Splitter** node or use a different chunking strategy. See [Chunking Strategies for LLM Applications](https://www.pinecone.io/learn/chunking-strategies/) for more info.
  * Customize the system message of the **AI Agent** node to reflect what the **Pinecone Vector Store Tool** will be used for.
  * Customize the description of the **Pinecone Vector Store Tool** to reflect what data you are storing in the Pinecone index.
* Use n8n, Pinecone Assistant, and OpenAI to [chat with your Google Drive documents](https://n8n.io/workflows/9942-rag-powered-document-chat-with-google-drive-openai-and-pinecone-assistant/).
* Get help in the [Pinecone Discord community](https://discord.gg/tJ8V62S3sH).


# Test Pinecone at scale
Source: https://docs.pinecone.io/guides/get-started/test-at-scale

Benchmark Pinecone at production scale by importing 10M vectors and measuring semantic search throughput, query latency, and costs.

This guide walks you through testing Pinecone at production scale. You'll import 10 million vectors, run a benchmark, and analyze the results to verify Pinecone meets production requirements for semantic search applications.

<Note>
  This test requires a Pinecone account on the Standard or Enterprise plan because it uses [import from object storage](/guides/index-data/import-data), which is not available on the Starter or Builder plans. New users can sign up for the [Standard trial](/guides/organizations/manage-billing/standard-trial) for 21 days and \$300 in credits, more than enough to cover the costs of this test. Existing users on the Starter or Builder plan can [upgrade](/guides/organizations/manage-billing/upgrade-billing-plan).
</Note>

## About this test

Semantic search enables finding relevant content based on meaning rather than exact keyword matches, making it ideal for applications like product search, content recommendation, and question-answering systems. This test simulates a production-scale semantic search workload, measuring import time, query throughput, query latency, and associated costs.

The test uses the following configuration:

* **Records**: 10 million records from the [Amazon Reviews 2023](https://amazon-reviews-2023.github.io/) dataset
* **Embedding model**: `llama-text-embed-v2` (1024 dimensions)
* **Similarity metric**: cosine
* **Total size**: 48.8 GB
* **Query load**: 10 queries per second total (across all users)
* **Concurrent users**: 10 users querying simultaneously
* **Test queries**: 100,000 queries
* **Import time target**: \< 30 minutes
* **Query latency target**: p90 latency \< 100ms

**Estimated cost**: \~\$127 (import: \$48.80, queries: \$78.08, storage: \$0.09) — see [detailed cost breakdown](#6-check-costs)

## 1. Get an API key

To follow the steps in this guide, you'll need an API key. Create a new API key in the [Pinecone console](https://app.pinecone.io/organizations/-/keys), or use this widget:

<div>
  <div>
    <div>
      <div />
    </div>
  </div>
</div>

Your generated API key:

```shell theme={null}
"{{YOUR_API_KEY}}"
```

## 2. Create an index

<Note>
  This test requires you to use AWS-based indexes and infrastructure. The sample dataset is only available from Amazon S3, and you can only import from Amazon S3 to Pinecone indexes hosted on AWS. To run the benchmark, you'll need to provision an AWS EC2 instance in the same region as your index.
</Note>

Create an on-demand index that matches the dimensions and similarity metric of the dataset you'll import in later steps.

<Tabs>
  <Tab title="Console">
    1. In the Pinecone console, go to the [Indexes](https://app.pinecone.io/organizations/-/projects/-/indexes) page.
    2. Click **Create index**.
    3. Check **Custom settings**.
    4. Configure the index with the following settings:
       * **Name**: `search-10m`
       * **Vector type**: Dense
       * **Dimensions**: `1024`
       * **Metric**: cosine
       * **Capacity mode**: Serverless (on-demand)
       * **Cloud**: AWS (required for this test)
       * **Region**: Use an AWS region appropriate for your use case (for example, `us-east-1`)
    5. Click **Create index**.
  </Tab>

  <Tab title="Code">
    If using code to create an index, first install the [Python SDK](/reference/python-sdk):

    ```shell Terminal theme={null}
    pip install pinecone
    ```

    Then, create the index:

    <CodeGroup>
      ```python Python theme={null}
      from pinecone import Pinecone, ServerlessSpec

      pc = Pinecone(api_key="{{YOUR_API_KEY}}")

      index_name = "search-10m"

      if not pc.has_index(index_name):
          pc.create_index(
              name=index_name,
              vector_type="dense",
              dimension=1024,
              metric="cosine",
              spec=ServerlessSpec(
                  # AWS is required for this test
                  cloud="aws",   
                  # Use an AWS region appropriate for your use case
                  region="us-east-1" 
              )
          )
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## 3. Import the dataset

Pinecone's [import feature](/guides/index-data/import-data) enables you to load millions of vectors from object storage in parallel. In this step, you'll import 10 million records into a single namespace (`ns_2`) in your index.

### Choose an import source

To import the dataset, you'll need to use the following Amazon S3 import URL:

```
s3://fe-customer-pocs/search/search_10M/dense/
```

### Start and monitor the import

For this dataset, the import should take less than 30 minutes.

<Tabs>
  <Tab title="Console">
    1. In the Pinecone console, go to the [Indexes](https://app.pinecone.io/organizations/-/projects/-/indexes) page.
    2. Find your `search-10m` index and click **... > Import data**.
    3. For **Storage integration**, select **No integration (public bucket)**.
    4. Enter the import URL: `s3://fe-customer-pocs/search/search_10M/dense/`.
    5. For **Error handling**, select **Abort on error (default)**.
    6. Click **Start import**.

    To monitor progress, open your index in the Pinecone console and navigate to the **Imports** tab. After the import completes, compare the **Started time** and **End time** timestamps to see the total time required.

    <Note>
      For this dataset, the import should take around 30 minutes. While the import is running, you can continue with the next step to provision a VM and install VSB. However, wait for the import to complete before running the benchmark.
    </Note>
  </Tab>

  <Tab title="Code">
    Start the import:

    <CodeGroup>
      ```python Python theme={null}
      from pinecone import Pinecone, ImportErrorMode

      pc = Pinecone(api_key="{{YOUR_API_KEY}}")
      index = pc.Index("search-10m")

      import_response = index.start_import(
          uri="s3://fe-customer-pocs/search/search_10M/dense/",
          error_mode=ImportErrorMode.ABORT 
      )
      print(f"Import started: {import_response['id']}")
      ```
    </CodeGroup>

    Monitor import progress:

    <CodeGroup>
      ```python Python theme={null}
      from pinecone import Pinecone
      import time 

      pc = Pinecone(api_key="{{YOUR_API_KEY}}")
      index = pc.Index("search-10m")

      while True:
          status = index.describe_import(id="IMPORT_ID")
          print(f"Status: {status['status']}, Progress: {status['percent_complete']:.1f}%")
          if status['status'] == "Completed":
              print("Import completed successfully!")
              break
          elif status['status'] == "Failed":
              print("Import failed. Check error details.")
              break
          elif status['status'] == "Cancelled":
              print("Import cancelled.")
              break
          time.sleep(15) # Check every 15 seconds
      ```
    </CodeGroup>

    <Note>
      There are three ways to find the import ID:

      * It's returned when the import is started
      * In the Pinecone console, on the **Imports** tab for your index
      * By calling [List imports](/reference/api/latest/data-plane/list_imports)
    </Note>
  </Tab>
</Tabs>

## 4. Run the benchmark

To simulate realistic query patterns and measure latency and throughput for your Pinecone index, use [Vector Search Bench (VSB)](https://github.com/pinecone-io/VSB). The benchmark runs 100,000 queries at 10 queries per second, which should take just under three hours to complete.

<Steps>
  <Step title="Provision a VM">
    VSB reports latency as the time from when the tool issues a query to when the query is returned by Pinecone.

    To minimize the client-side latency between the tool and Pinecone, run the benchmark on a dedicated AWS EC2 instance that's hosted in the same AWS region as your Pinecone index. This reduces the client-side latency to sub-millisecond range.

    <Note>
      As noted in [section 2](#2-create-an-index), this test requires an AWS EC2 instance in the same region as your index.
    </Note>

    For instructions on how to provision an EC2 instance, see the [AWS documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/LaunchingAndUsingInstances.html).

    <Note>
      Create a VM that comes with Python 3.11 or higher.
    </Note>
  </Step>

  <Step title="Connect to the VM">
    Connect to the VM using SSH or the cloud provider's console.
  </Step>

  <Step title="Install Vector Search Bench (VSB)">
    [VSB (Vector Search Bench)](https://github.com/pinecone-io/VSB) is a benchmarking suite for testing vector database search performance across different workloads and databases. To install it, you'll first need to install various dependencies.

    1. **Verify Python version**

       VSB requires Python 3.11 or higher to run. Verify your Python version:

       ```bash Terminal theme={null}
       python3 --version
       ```

       If your version is below 3.11, install Python 3.11+ using your distribution's package manager.

    2. **Install git**

       Git is required to clone the VSB repository. Check if git is installed:

       ```bash Terminal theme={null}
       git --version
       ```

       If git is not installed, install it using your system's package manager:

       ```bash Terminal theme={null}
       # Adapt for your VM's package manager (apt/yum/dnf)
       sudo apt-get update && sudo apt-get install git
       ```

    3. **Install pipx**

       pipx is required to install Poetry. First, check if pip3 is installed:

       ```bash Terminal theme={null}
       pip3 --version
       ```

       If pip is not installed, install it using your system's package manager:

       ```bash Terminal theme={null}
       # Adapt for your VM's package manager (apt/yum/dnf)
       sudo apt-get update && sudo apt-get install python3-pip
       ```

       Then check if pipx is installed:

       ```bash Terminal theme={null}
       pipx --version
       ```

       If pipx is not installed, install it via your system's package manager:

       ```bash Terminal theme={null}
       # Adapt for your VM's package manager (apt/yum/dnf)
       sudo apt-get update && sudo apt-get install pipx
       pipx ensurepath
       ```

       After installation, run this command to update the PATH in your current terminal session:

       ```bash Terminal theme={null}
       source ~/.bashrc
       ```

    4. **Install Poetry**

       [Poetry](https://python-poetry.org/) is required to manage [VSB's](https://github.com/pinecone-io/VSB) Python dependencies and virtual environment. If Poetry is not [installed](https://python-poetry.org/docs/), use pipx to install it:

       ```bash Terminal theme={null}
       pipx install poetry
       ```

       Alternatively, use the [official Poetry installer](https://python-poetry.org/docs/#installing-with-the-official-installer).

    5. **Clone the VSB repository**

       To run the benchmark, you'll first need to clone the VSB repository and navigate to it:

       ```bash Terminal theme={null}
       git clone https://github.com/pinecone-io/VSB.git
       cd VSB
       ```

    6. **Configure Poetry**

       Since your VM has Python 3.11 or higher installed (as specified in the VM provisioning step), tell Poetry to use it:

       ```bash Terminal theme={null}
       poetry env use python3
       ```

    7. **Install dependencies**

       VSB requires several Python packages to run. Install all dependencies:

       ```bash Terminal theme={null}
       poetry install
       ```
  </Step>

  <Step title="Benchmark your Pinecone index">
    To test the performance of your Pinecone index, run the following command from within the `VSB` directory. For more information about VSB, see its [GitHub repository](https://github.com/pinecone-io/VSB).

    The following command simulates 10 concurrent users issuing a total of 100,000 queries at 10 queries per second (QPS). Each query performs a vector search for the top 10 most similar 1024-dimensional vectors, using cosine similarity, with query vectors selected uniformly at random. The `--skip_populate` flag skips the data population phase, since you've already imported data into your index.

    ```bash Terminal theme={null}
    poetry run vsb \
        --database="pinecone" \
        --workload=synthetic-proportional \
        --pinecone_api_key="{{YOUR_API_KEY}}" \
        --pinecone_index_name="search-10m" \
        --pinecone_namespace_name="ns_2" \
        --synthetic_dimensions=1024 \
        --synthetic_metric=cosine \
        --synthetic_top_k=10 \
        --synthetic_requests=100000 \
        --users=10 \
        --requests_per_sec=10 \
        --synthetic_query_distribution=uniform \
        --synthetic_query_ratio=1 \
        --synthetic_insert_ratio=0 \
        --synthetic_delete_ratio=0 \
        --synthetic_update_ratio=0 \
        --skip_populate
    ```
  </Step>
</Steps>

## 5. Analyze performance

At the end of the run, VSB prints an operation summary including the requests per second achieved and latencies at different percentiles. Here's an example output:

```shell Terminal theme={null}
2025-12-23T00:34:37 INFO     Completed Run phase, took 9940.14s

                      Operation Summary

  Operation  Requests  Failures  Requests/sec  Failures/sec
 ───────────────────────────────────────────────────────────
  Search        99000     0(0%)            10           0.0

                                                    Metrics Summary

  Operation  Metric         Min  0.1%    1%    5%   10%   25%   50%   75%   90%   95%   99%  99.9%  99.99%   Max  Mean
 ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  Search     Latency (ms)    23    25    25    26    27    27    29    34    44    81   350    430    1300  4602    43
```

Confirm that the requests per second achieved is around 10 QPS and the p90 latency is less than 100ms.

To see more detailed statistics, you can analyze the `stats.json` file identified in the output.

## 6. Check costs

You can check the costs for the import, queries, and storage in the Pinecone console at [Settings > Usage](https://app.pinecone.io/organizations/-/settings/usage). Cost data is delayed up to three days, but once it's available, compare the actual costs to the estimated costs below.

<Note>For the latest pricing details, see [Pricing](https://www.pinecone.io/pricing).</Note>

| Cost type | Amount          | Pricing                | Estimated cost |
| :-------- | :-------------- | :--------------------- | :------------- |
| Import    | 48.8 GB         | \$0.25/GB              | \$12.20        |
| Queries   | 100,000 queries | \$16 per 1M read units | \$78.08        |
| Storage   | 4 hours         | \$0.33/GB/month        | \$0.09         |
| **Total** |                 |                        | **\$90.37**    |

<Note>Standard and Enterprise organizations receive a **one-time 1 TB bulk import credit**, valid through August 30, 2026, so on those plans the import portion of this example would be \$0 and the total would be \$78.17. The figures above assume the standard overage rate.</Note>

<Steps>
  <Step title="Import costs">
    The current price for import is \$0.25/GB. The dataset size for this test is 48.8 GB, so the import cost should be \$12.20.
  </Step>

  <Step title="Query costs">
    A query uses 1 [read unit (RU)](/guides/manage-cost/understanding-cost#read-units) for every 1 GB of namespace size. The current price for queries in the `us-east-1` region of AWS is \$16 per 1 million read units (pricing varies by region).

    This test ran 100,000 queries against a namespace size of 48.8 GB. Each query uses 48.8 RUs (1 RU per GB), so the total is 4,880,000 RUs. At \$16 per 1 million RUs, the cost is (4,880,000 / 1,000,000) × \$16 = \$78.08.
  </Step>

  <Step title="Storage costs">
    The current price for storage is \$0.33 per GB per month. The dataset size for this test is 48.8 GB. Assuming a total storage time of 4 hours (including import, benchmark runtime, and cleanup), the storage cost is: \$0.33/GB/month \* 48.8 GB / 730 hours \* 4 hours = \$0.09.
  </Step>

  <Step title="Total costs">
    The total cost for the test is the sum of the import cost, query cost, and storage cost: \$12.20 + \$78.08 + \$0.09 = \$90.37.
  </Step>
</Steps>

## 7. Clean up

When you no longer need your test index, [delete it](/guides/manage-data/manage-indexes#delete-an-index) to avoid incurring unnecessary costs.


# Check data freshness
Source: https://docs.pinecone.io/guides/index-data/check-data-freshness

Check data freshness in Pinecone serverless indexes using log sequence numbers (LSNs) and vector counts to verify recent upserts and deletes.

Pinecone is eventually consistent, so there can be a slight delay before new or changed records are visible to queries. This page describes two ways of checking the data freshness of a Pinecone index:

* To check if a serverless index queries reflect recent writes to the index, [check the log sequence number](#check-the-log-sequence-number).

* To check whether an index contains recently inserted or deleted vectors, [verify the number of vectors in the index](#verify-vector-counts).

## Check the log sequence number

<Note>
  This method is only available for serverless indexes through the [Database API](https://docs.pinecone.io/reference/api/latest/data-plane/upsert).
</Note>

### Log sequence numbers

When you make a write request to a serverless index namespace, Pinecone assigns a monotonically increasing log sequence number (LSN) to the write operation. The LSN reflects upserts as well as updates and deletes to that namespace. Writes to one namespace do not increase the LSN for other namespaces.

You can use LSNs to verify that specific write operations are reflected in your query responses. If the LSN contained in the query response header is greater than or equal to the LSN of the relevant write operation, then that operation is reflected in the query response. If the LSN contained in the query response header is *greater than* the LSN of the relevant write operation, then subsequent operations are also reflected in the query response.

Follow the steps below to compare the LSNs for a write and a subsequent query.

### 1. Get the LSN for a write operation

Every time you modify records in your namespace, the HTTP response contains the LSN for the upsert. This is contained in a header called `x-pinecone-request-lsn`.

The following example demonstrates how to get the LSN for an `upsert` request using the `curl` option `-i`. This option tells curl to include headers in the displayed response. Use the same method to get the LSN for an `update` or `delete` request.

```shell curl theme={null}
PINECONE_API_KEY="YOUR_API_KEY"
INDEX_HOST="INDEX_HOST"

curl -i "https://$INDEX_HOST/vectors/upsert" \
  -H "Api-Key: $PINECONE_API_KEY" \
  -H "content-type: application/json" \
  -H "X-Pinecone-Api-Version: 2025-10" \
  -d '{
        "vectors": [
          {
            "id": "vec1",
            "values": [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8],
          }
        ],
        "namespace": "example-namespace"
      }'
```

The preceding request receives a response like the following example:

```shell curl theme={null}
HTTP/2 200 
date: Wed, 21 Aug 2024 15:23:04 GMT
content-type: application/json
content-length: 66
x-pinecone-request-lsn: 4
x-pinecone-request-latency-ms: 1149
x-pinecone-request-id: 3687967458925971419
x-envoy-upstream-service-time: 1150
grpc-status: 0
server: envoy

{"upsertedCount":1}
```

In the preceding example response, the value of `x-pinecone-request-lsn` is 4. This is the LSN assigned to this write operation; use it to compare against the query response LSN in the next step.

### 2. Get the LSN for a query

Every time you query your index, the HTTP response contains the LSN for the query. This is contained in a header called `x-pinecone-max-indexed-lsn`.

By checking the LSN in your query results, you can confirm that the LSN is greater than or equal to the LSN of the relevant write operation, indicating that the results of that operation are present in the query results.

The following example makes a `query` request to the index:

```shell curl theme={null}
PINECONE_API_KEY="YOUR_API_KEY"
INDEX_HOST="INDEX_HOST"

curl -i "https://$INDEX_HOST/query" \
  -H "Api-Key: $PINECONE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "X-Pinecone-Api-Version: 2025-10" \
  -d '{
    "vector": [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3],
    "namespace": "example-namespace",
    "topK": 3,
    "includeValues": true
  }'
```

The preceding request receives a response like the following example:

```shell theme={null}
HTTP/2 200 
date: Wed, 21 Aug 2024 15:33:36 GMT
content-type: application/json
content-length: 66
x-pinecone-max-indexed-lsn: 5
x-pinecone-request-latency-ms: 40
x-pinecone-request-id: 6683088825552978933
x-envoy-upstream-service-time: 41
grpc-status: 0
server: envoy

{
  "results":[],
  "matches":[
    {
      "id":"vec1",
      "score":0.891132772,
      "values":[0.1,0.2,0.3,0.4,0.5,0.6,0.7,0.8],
    }
  ],
  "namespace":"example-namespace",
  "usage":{"readUnits":6}
}
```

In the preceding example response, the value of `x-pinecone-max-indexed-lsn` is 5.

### 3. Compare LSNs for writes and queries

If the LSN of a query is greater than or equal to the LSN for a write operation, then the results of the query reflect the results of the write operation.

In [step 1](#1-get-the-lsn-for-a-write-operation), the LSN contained in the response headers is 4.

In [step 2](#2-get-the-lsn-for-a-query), the LSN contained in the response headers is 5.

5 is greater than or equal to 4; therefore, the results of the query reflect the results of the upsert. However, this does not guarantee that the records upserted are still present or unmodified: the write operation with LSN of 5 may have updated or deleted these records, or upserted additional records.

## Verify record counts

If you insert new records or delete records, the number of records in the index may change. This means that the record count for an index can indicate whether Pinecone has indexed your latest inserts and deletes: if the record count for the index matches the count you expect after inserting or deleting records, the index is probably up-to-date. However, this is not always true. For example, if you delete the same number of records that you insert, the expected record count may remain the same. Also, some write operations, such as updates to an index configuration or vector data values, do not change the number of records in the index.

To verify that your index contains the number of records you expect, [view index stats](/reference/api/latest/data-plane/describeindexstats):

<CodeGroup>
  ```python Python theme={null}
  # pip install "pinecone[grpc]"
  from pinecone.grpc import PineconeGRPC as Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")

  # To get the unique host for an index, 
  # see https://docs.pinecone.io/guides/manage-data/target-an-index
  index = pc.Index(host="INDEX_HOST")

  index.describe_index_stats()
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone'

  const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' })

  // To get the unique host for an index, 
  // see https://docs.pinecone.io/guides/manage-data/target-an-index
  const index = pc.index("INDEX_NAME", "INDEX_HOST")

  const stats = await index.describeIndexStats();
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Index;
  import io.pinecone.configs.PineconeConfig;
  import io.pinecone.configs.PineconeConnection;
  import io.pinecone.proto.DescribeIndexStatsResponse;

  public class DescribeIndexStatsExample {
      public static void main(String[] args) {
          PineconeConfig config = new PineconeConfig("YOUR_API_KEY");
          // To get the unique host for an index, 
          // see https://docs.pinecone.io/guides/manage-data/target-an-index
          config.setHost("INDEX_HOST");
          PineconeConnection connection = new PineconeConnection(config);
          Index index = new Index(connection, "INDEX_NAME");
          DescribeIndexStatsResponse indexStatsResponse = index.describeIndexStats();
          System.out.println(indexStatsResponse);
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "log"

      "github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

      // To get the unique host for an index, 
      // see https://docs.pinecone.io/guides/manage-data/target-an-index
      idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST"})
      if err != nil {
          log.Fatalf("Failed to create IndexConnection for Host: %v", err)
    	}

      stats, err := idxConnection.DescribeIndexStats(ctx)
      if err != nil {
          log.Fatalf("Failed to describe index \"%v\": %v", idx.Name, err)
      } else {
          fmt.Printf("%+v", *stats)
      }
  }
  ```

  ```shell curl theme={null}
  # To get the unique host for an index,
  # see https://docs.pinecone.io/guides/manage-data/target-an-index
  PINECONE_API_KEY="YOUR_API_KEY"
  INDEX_HOST="INDEX_HOST"

  curl -X POST "https://$INDEX_HOST/describe_index_stats" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2025-10"
  ```
</CodeGroup>

The response will look like this:

<CodeGroup>
  ```Python Python theme={null}
  {'dimension': 1024,
   'index_fullness': 0,
   'namespaces': {'example-namespace1': {'vector_count': 4}, 'example-namespace2': {'vector_count': 4}},
   'total_vector_count': 8}
  ```

  ```JavaScript JavaScript theme={null}
  Returns:
  {
    namespaces: { example-namespace1: { recordCount: 4 }, example-namespace2: { recordCount: 4 } },
    dimension: 1024,
    indexFullness: 0,
    totalRecordCount: 8
  }

  // Note: the value of totalRecordCount is the same as total_vector_count.
  ```

  ```java Java theme={null}
  namespaces {
    key: "example-namespace1"
    value {
      vector_count: 4
    }
  }
  namespaces {
    key: "example-namespace2"
    value {
      vector_count: 4
    }
  }
  dimension: 1024
  total_vector_count: 8
  ```

  ```go Go theme={null}
  {
    "dimension": 1024,
    "index_fullness": 0,
    "total_vector_count": 8,
    "namespaces": {
      "example-namespace1": {
        "vector_count": 4
      },
      "example-namespace2": {
        "vector_count": 4
      }
    }
  }
  ```

  ```shell curl theme={null}
  {
    "namespaces": {
      "example-namespace1": {
        "vectorCount": 4
      },
      "example-namespace2": {
        "vectorCount": 4
      }
    },
    "dimension": 1024,
    "indexFullness": 0,
    "totalVectorCount": 8
  }
  ```
</CodeGroup>


# Create an index
Source: https://docs.pinecone.io/guides/index-data/create-an-index

Create a Pinecone serverless index for full-text (BM25), semantic (dense vector), lexical (sparse), or hybrid search with a document schema.

A Pinecone index can hold any combination of the following:

* **Documents** are the unit of data in an index with a document schema — JSON records whose ranking fields are indexed according to a schema you declare at index creation. An index with a document schema can mix `dense_vector`, `sparse_vector`, and FTS-enabled `string` ranking fields in the same record, alongside any number of metadata fields (auto-indexed at upsert time). Use documents for [full-text search](/guides/search/full-text-search) (BM25 ranking on `string` fields with `full_text_search` enabled), and to combine multiple scoring methods on the same data via `score_by`.

* **Dense vectors** are numerical representations of the meaning and relationships of text, images, or other data. Indexes of dense vectors are used for [semantic search](/guides/search/semantic-search), or together with sparse vectors for [hybrid search](/guides/search/hybrid-search).

* **Sparse vectors** are high-dimensional vectors with mostly zero values, produced by a sparse embedding model such as [`pinecone-sparse-english-v0`](/models/pinecone-sparse-english-v0). Indexes of sparse vectors are used for [sparse-vector lexical search](/guides/search/lexical-search), or together with dense vectors for [hybrid search](/guides/search/hybrid-search).

<Tip>
  You can create an index using the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/create-index/serverless).
</Tip>

## Create an index for full-text search

An index with a document schema stores typed JSON documents. The schema declares how each ranking field is indexed: as a `string` field with `full_text_search` enabled for BM25 ranking, a `dense_vector` for ANN similarity, or a `sparse_vector`. A single index can mix all three ranking field types; at query time, pick the ranking signal with `score_by`. Metadata fields (anything else you upsert) are not declared in the schema — they're auto-indexed for filtering at upsert time.

<Note>
  Full-text search is not integrated embedding. A `string` field with `full_text_search` is indexed for BM25 ranking and Lucene queries. It does not call an embedding model. Integrated embedding remains available for vector API indexes.
</Note>

Indexes with document schemas are in [public preview](/guides/search/full-text-search#public-preview) and use API version `2026-01.alpha`. The preview supports REST and the Python SDK; for other languages, call the REST endpoint directly.

### Minimal: BM25 on a single text field

The example below creates an `articles` index whose `body` field is indexed for BM25 ranking. Other fields included at upsert time are stored on each document and auto-indexed for filtering as metadata.

```bash curl theme={null}
curl -X POST "https://api.pinecone.io/indexes" \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Pinecone-Api-Version: 2026-01.alpha" \
  -d '{
    "name": "articles",
    "deployment": {
      "deployment_type": "managed",
      "cloud": "aws",
      "region": "us-east-1"
    },
    "schema": {
      "fields": {
        "body": {
          "type": "string",
          "full_text_search": {}
        }
      }
    }
  }'
```

### Multi-field schema: BM25 + dense vector

A single index with a document schema can hold FTS-enabled `string` and `dense_vector` ranking fields together (the same schema can also include a `sparse_vector` field). A single search request ranks by one scoring type — multi-field BM25 is supported (multiple `text` clauses on different fields, or one `query_string` clause spanning fields), and any scoring method can be combined with metadata filters, including text-match filters (`$match_phrase`, `$match_all`, `$match_any`) on FTS-enabled `string` fields.

```bash curl theme={null}
curl -X POST "https://api.pinecone.io/indexes" \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Pinecone-Api-Version: 2026-01.alpha" \
  -d '{
    "name": "articles-multi",
    "deployment": {
      "deployment_type": "managed",
      "cloud": "aws",
      "region": "us-east-1"
    },
    "schema": {
      "fields": {
        "title":    { "type": "string", "full_text_search": {} },
        "body":     { "type": "string", "full_text_search": {} },
        "embedding":{ "type": "dense_vector", "dimension": 1536, "metric": "cosine" }
      }
    }
  }'
```

You can include additional fields (for example, `category` or `year`) at upsert time. All metadata fields are automatically indexed for filtering — they don't need to be declared in the schema. The schema is for ranking fields only; declaring a metadata-only field (`string` without `full_text_search`, `string_list`, `float`, or `boolean`) is rejected at index creation.

For the full schema reference (all field types, language and analyzer options, dedicated read capacity, and Python SDK examples), see [Full-text search](/guides/search/full-text-search).

<Warning>
  Schema migration is not yet supported. Once an index with a document schema is created, you cannot add, remove, or modify fields. Plan your schema carefully — if you need to change a schema, [delete the index](/guides/manage-data/manage-indexes#delete-an-index) and create a new one.
</Warning>

## Create an index for dense vectors

You can create an index that stores dense vectors with [integrated vector embedding](/guides/index-data/indexing-overview#integrated-embedding), or one that stores vectors generated with an external embedding model.

### Integrated embedding

<Note>
  Indexes with integrated embedding do not support [updating](/guides/manage-data/update-data) or [importing](/guides/index-data/import-data) with text.
</Note>

If you want to upsert and search with source text and have Pinecone convert it to dense vectors automatically, [create an index with integrated embedding](/reference/api/latest/control-plane/create_for_model) as follows:

* Provide a `name` for the index.
* Set `cloud` and `region` to the [cloud and region](/guides/index-data/create-an-index#cloud-regions) where the index should be deployed.
* Set `embed.model` to one of [Pinecone's hosted embedding models](/guides/index-data/create-an-index#embedding-models).
* Set `embed.field_map` to the name of the field in your source document that contains the data for embedding.

Other parameters are optional. See the [API reference](/reference/api/latest/control-plane/create_for_model) for details.

<CodeGroup>
  ```python Python theme={null}
  from pinecone import Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")

  index_name = "integrated-dense-py"

  if not pc.has_index(index_name):
      pc.create_index_for_model(
          name=index_name,
          cloud="aws",
          region="us-east-1",
          embed={
              "model":"llama-text-embed-v2",
              "field_map":{"text": "chunk_text"}
          }
      )
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone'

  const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' });

  await pc.createIndexForModel({
    name: 'integrated-dense-js',
    cloud: 'aws',
    region: 'us-east-1',
    embed: {
      model: 'llama-text-embed-v2',
      fieldMap: { text: 'chunk_text' },
    },
    waitUntilReady: true,
  });
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Pinecone;
  import org.openapitools.db_control.client.ApiException;
  import org.openapitools.db_control.client.model.CreateIndexForModelRequest;
  import org.openapitools.db_control.client.model.CreateIndexForModelRequestEmbed;
  import org.openapitools.db_control.client.model.DeletionProtection;
  import java.util.HashMap;
  import java.util.Map;

  public class CreateIntegratedIndex {
      public static void main(String[] args) throws ApiException {
          Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build();
          String indexName = "integrated-dense-java";
          String region = "us-east-1";
          HashMap<String, String> fieldMap = new HashMap<>();
          fieldMap.put("text", "chunk_text");
          CreateIndexForModelRequestEmbed embed = new CreateIndexForModelRequestEmbed()
                  .model("llama-text-embed-v2")
                  .fieldMap(fieldMap);
          Map<String, String> tags = new HashMap<>();
          tags.put("environment", "development");
          pc.createIndexForModel(
                  indexName,
                  CreateIndexForModelRequest.CloudEnum.AWS,
                  region,
                  embed,
                  DeletionProtection.DISABLED,
                  tags
          );
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "fmt"
      "log"

      "github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

    	indexName := "integrated-dense-go"
     	deletionProtection := pinecone.DeletionProtectionDisabled

      idx, err := pc.CreateIndexForModel(ctx, &pinecone.CreateIndexForModelRequest{
  		Name:   indexName,
  		Cloud:  pinecone.Aws,
  		Region: "us-east-1",
  		Embed: pinecone.CreateIndexForModelEmbed{
  			Model:    "llama-text-embed-v2",
  			FieldMap: map[string]interface{}{"text": "chunk_text"},
  		},
          DeletionProtection: &deletionProtection,
          Tags:   &pinecone.IndexTags{ "environment": "development" },
  	})
      if err != nil {
          log.Fatalf("Failed to create serverless integrated index: %v", idx.Name)
      } else {
          fmt.Printf("Successfully created serverless integrated index: %v", idx.Name)
      }
  }
  ```

  ```json curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"

  curl -X POST "https://api.pinecone.io/indexes/create-for-model" \
       -H "Content-Type: application/json" \
       -H "Api-Key: $PINECONE_API_KEY" \
       -H "X-Pinecone-Api-Version: 2025-10" \
       -d '{
             "name": "integrated-dense-curl",
             "cloud": "aws",
             "region": "us-east-1",
             "embed": {
               "model": "llama-text-embed-v2",
               "field_map": {
                 "text": "chunk_text"
               }
             }
           }'
  ```

  ```bash CLI theme={null}
  # Target the project where you want to create the index.
  pc target -o "example-org" -p "example-project"
  # Create the index.
  pc index create \
    --name "integrated-dense-cli" \
    --metric "cosine" \
    --cloud "aws" \
    --region "us-east-1" \
    --model "llama-text-embed-v2" \
    --field_map "text=chunk_text" \
    --tags "environment=development"
  ```
</CodeGroup>

### Bring your own vectors

If you use an external embedding model to convert your data to dense vectors, [create an index](/reference/api/latest/control-plane/create_index) as follows:

* Provide a `name` for the index.
* Set the `vector_type` to `dense`.
* Specify the `dimension` and similarity `metric` of the vectors you'll store in the index. This should match the dimension and metric supported by your embedding model.
* Set `spec.cloud` and `spec.region` to the [cloud and region](/guides/index-data/create-an-index#cloud-regions) where the index should be deployed. For Python, you also need to import the `ServerlessSpec` class.

Other parameters are optional. See the [API reference](/reference/api/latest/control-plane/create_index) for details.

<CodeGroup>
  ```python Python theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone
  from pinecone import ServerlessSpec

  pc = Pinecone(api_key="YOUR_API_KEY")

  index_name = "standard-dense-py"

  if not pc.has_index(index_name):
      pc.create_index(
          name=index_name,
          vector_type="dense",
          dimension=1536,
          metric="cosine",
          spec=ServerlessSpec(
              cloud="aws",
              region="us-east-1"
          ),
          deletion_protection="disabled",
          tags={
              "environment": "development"
          }
      )
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone'

  const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' });

  await pc.createIndex({
    name: 'standard-dense-js',
    vectorType: 'dense',
    dimension: 1536,
    metric: 'cosine',
    spec: {
      serverless: {
        cloud: 'aws',
        region: 'us-east-1'
      }
    },
    deletionProtection: 'disabled',
    tags: { environment: 'development' }, 
  });
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Pinecone;
  import org.openapitools.db_control.client.model.IndexModel;
  import org.openapitools.db_control.client.model.DeletionProtection;
  import java.util.HashMap;

  public class CreateServerlessIndexExample {
      public static void main(String[] args) {
          Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build();
          String indexName = "standard-dense-java";
          String cloud = "aws";
          String region = "us-east-1";
          String vectorType = "dense";
          Map<String, String> tags = new HashMap<>();
          tags.put("environment", "development");
          pc.createServerlessIndex(
              indexName,
              "cosine", 
              1536, 
              cloud,
              region,
              DeletionProtection.DISABLED, 
              tags, 
              vectorType
          );
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "fmt"
      "log"

      "github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

      // Serverless index
    	indexName := "standard-dense-go"
  	vectorType := "dense"
      dimension := int32(1536)
      metric := pinecone.Cosine
  	deletionProtection := pinecone.DeletionProtectionDisabled

      idx, err := pc.CreateServerlessIndex(ctx, &pinecone.CreateServerlessIndexRequest{
          Name:               indexName,
          VectorType:         &vectorType,
          Dimension:          &dimension,
          Metric:             &metric,
          Cloud:              pinecone.Aws,
          Region:             "us-east-1",
          DeletionProtection: &deletionProtection,
          Tags:               &pinecone.IndexTags{ "environment": "development" },
      })
      if err != nil {
          log.Fatalf("Failed to create serverless index: %v", err)
      } else {
          fmt.Printf("Successfully created serverless index: %v", idx.Name)
      }
  }
  ```

  ```shell curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"

  curl -X POST "https://api.pinecone.io/indexes" \
       -H "Accept: application/json" \
       -H "Content-Type: application/json" \
       -H "Api-Key: $PINECONE_API_KEY" \
       -H "X-Pinecone-Api-Version: 2025-10" \
       -d '{
             "name": "standard-dense-curl",
             "vector_type": "dense",
             "dimension": 1536,
             "metric": "cosine",
             "spec": {
               "serverless": {
                 "cloud": "aws",
                 "region": "us-east-1"
                }
              },
              "tags": {
                "environment": "development"
              },
              "deletion_protection": "disabled"
           }'
  ```

  ```bash CLI theme={null}
  # Target the project where you want to create the index.
  pc target -o "example-org" -p "example-project"
  # Create the index.
  pc index create \
    --name "standard-dense-cli" \
    --vector_type "dense" \
    --dimension 1536 \
    --metric "cosine" \
    --cloud "aws" \
    --region "us-east-1" \
    --tags "environment=development" \
    --deletion_protection "disabled"
  ```
</CodeGroup>

## Create an index for sparse vectors

You can create an index that stores sparse vectors with [integrated vector embedding](/guides/index-data/indexing-overview#integrated-embedding), or one that stores vectors generated with an external embedding model.

### Integrated embedding

If you want to upsert and search with source text and have Pinecone convert it to sparse vectors automatically, [create an index with integrated embedding](/reference/api/latest/control-plane/create_for_model) as follows:

* Provide a `name` for the index.
* Set `cloud` and `region` to the [cloud and region](/guides/index-data/create-an-index#cloud-regions) where the index should be deployed.
* Set `embed.model` to one of [Pinecone's hosted sparse embedding models](/guides/index-data/create-an-index#embedding-models).
* Set `embed.field_map` to the name of the field in your source document that contains the text for embedding.
* If needed, `embed.read_parameters` and `embed.write_parameters` can be used to override the default model embedding behavior.

Other parameters are optional. See the [API reference](/reference/api/latest/control-plane/create_for_model) for details.

<CodeGroup>
  ```python Python theme={null}
  from pinecone import Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")

  index_name = "integrated-sparse-py"

  if not pc.has_index(index_name):
      pc.create_index_for_model(
          name=index_name,
          cloud="aws",
          region="us-east-1",
          embed={
              "model":"pinecone-sparse-english-v0",
              "field_map":{"text": "chunk_text"}
          }
      )
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone'

  const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' });

  await pc.createIndexForModel({
    name: 'integrated-sparse-js',
    cloud: 'aws',
    region: 'us-east-1',
    embed: {
      model: 'pinecone-sparse-english-v0',
      fieldMap: { text: 'chunk_text' },
    },
    waitUntilReady: true,
  });
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Pinecone;
  import org.openapitools.db_control.client.ApiException;
  import org.openapitools.db_control.client.model.CreateIndexForModelRequest;
  import org.openapitools.db_control.client.model.CreateIndexForModelRequestEmbed;
  import org.openapitools.db_control.client.model.DeletionProtection;
  import java.util.HashMap;
  import java.util.Map;

  public class CreateIntegratedIndex {
      public static void main(String[] args) throws ApiException {
          Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build();
          String indexName = "integrated-sparse-java";
          String region = "us-east-1";
          HashMap<String, String> fieldMap = new HashMap<>();
          fieldMap.put("text", "chunk_text");
          CreateIndexForModelRequestEmbed embed = new CreateIndexForModelRequestEmbed()
                  .model("pinecone-sparse-english-v0")
                  .fieldMap(fieldMap);
          Map<String, String> tags = new HashMap<>();
          tags.put("environment", "development");
          pc.createIndexForModel(
                  indexName,
                  CreateIndexForModelRequest.CloudEnum.AWS,
                  region,
                  embed,
                  DeletionProtection.DISABLED,
                  tags
          );
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "fmt"
      "log"

      "github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

    	indexName := "integrated-sparse-go"
  	deletionProtection := pinecone.DeletionProtectionDisabled

      idx, err := pc.CreateIndexForModel(ctx, &pinecone.CreateIndexForModelRequest{
  		Name:   indexName,
  		Cloud:  pinecone.Aws,
  		Region: "us-east-1",
  		Embed: pinecone.CreateIndexForModelEmbed{
  			Model:    "pinecone-sparse-english-v0",
  			FieldMap: map[string]interface{}{"text": "chunk_text"},
  		},
          DeletionProtection: &deletionProtection,
          Tags:   &pinecone.IndexTags{ "environment": "development" },

  	})
      if err != nil {
          log.Fatalf("Failed to create serverless integrated index: %v", idx.Name)
      } else {
          fmt.Printf("Successfully created serverless integrated index: %v", idx.Name)
      }
  }
  ```

  ```shell curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"

  curl -X POST "https://api.pinecone.io/indexes/create-for-model" \
       -H "Content-Type: application/json" \
       -H "Api-Key: $PINECONE_API_KEY" \
       -H "X-Pinecone-Api-Version: 2025-10" \
       -d '{
             "name": "integrated-sparse-curl",
             "cloud": "aws",
             "region": "us-east-1",
             "embed": {
               "model": "pinecone-sparse-english-v0",
               "field_map": {
                 "text": "chunk_text"
               }
             }
           }'
  ```

  ```bash CLI theme={null}
  # Target the project where you want to create the index.
  pc target -o "example-org" -p "example-project"
  # Create the index.
  pc index create \
    --name "integrated-sparse-cli" \
    --cloud "aws" \
    --region "us-east-1" \
    --model "pinecone-sparse-english-v0" \
    --field_map "text=chunk_text" \
    --tags "environment=development"
  ```
</CodeGroup>

### Bring your own vectors

If you use an external embedding model to convert your data to sparse vectors, [create an index](/reference/api/latest/control-plane/create_index) as follows:

* Provide a `name` for the index.
* Set the `vector_type` to `sparse`.
* Set the distance `metric` to `dotproduct`. Indexes that store sparse vectors do not support other [distance metrics](/guides/index-data/indexing-overview#distance-metrics).
* Set `spec.cloud` and `spec.region` to the cloud and region where the index should be deployed.

Other parameters are optional. See the [API reference](/reference/api/latest/control-plane/create_index) for details.

<CodeGroup>
  ```python Python theme={null}
  from pinecone import Pinecone, ServerlessSpec

  pc = Pinecone(api_key="YOUR_API_KEY")

  index_name = "standard-sparse-py"

  if not pc.has_index(index_name):
      pc.create_index(
          name=index_name,
          vector_type="sparse",
          metric="dotproduct",
          spec=ServerlessSpec(cloud="aws", region="us-east-1")
      )
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone'

  const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' });

  await pc.createIndex({
    name: 'standard-sparse-js',
    vectorType: 'sparse',
    metric: 'dotproduct',
    spec: {
      serverless: {
        cloud: 'aws',
        region: 'us-east-1'
      },
    },
  });
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Pinecone;
  import org.openapitools.db_control.client.model.DeletionProtection;

  import java.util.*;

  public class SparseIndex {
      public static void main(String[] args) throws InterruptedException {
          // Instantiate Pinecone class
          Pinecone pinecone = new Pinecone.Builder("YOUR_API_KEY").build();

          // Create the index
          String indexName = "standard-sparse-java";
          String cloud = "aws";
          String region = "us-east-1";
          String vectorType = "sparse";
          Map<String, String> tags = new HashMap<>();
          tags.put("env", "test");
          pinecone.createSparseServelessIndex(indexName,
                  cloud,
                  region,
                  DeletionProtection.DISABLED,
                  tags,
                  vectorType);
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
  	"context"
  	"fmt"
  	"log"

  	"github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func main() {
  	ctx := context.Background()

  	pc, err := pinecone.NewClient(pinecone.NewClientParams{
  		ApiKey: "YOUR_API_KEY",
  	})
  	if err != nil {
  		log.Fatalf("Failed to create Client: %v", err)
  	}

  	indexName := "standard-sparse-go"
  	vectorType := "sparse"
  	metric := pinecone.Dotproduct
  	deletionProtection := pinecone.DeletionProtectionDisabled

  	idx, err := pc.CreateServerlessIndex(ctx, &pinecone.CreateServerlessIndexRequest{
  		Name:               indexName,
  		Metric:             &metric,
  		VectorType:         &vectorType,
  		Cloud:              pinecone.Aws,
  		Region:             "us-east-1",
  		DeletionProtection: &deletionProtection,
  	})
  	if err != nil {
  		log.Fatalf("Failed to create serverless index: %v", err)
  	} else {
  		fmt.Printf("Successfully created serverless index: %v", idx.Name)
  	}
  }
  ```

  ```shell curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"

  curl -X POST "https://api.pinecone.io/indexes" \
       -H "Accept: application/json" \
       -H "Content-Type: application/json" \
       -H "Api-Key: $PINECONE_API_KEY" \
       -H "X-Pinecone-Api-Version: 2025-10" \
       -d '{
              "name": "standard-sparse-curl",
              "vector_type": "sparse",
              "metric": "dotproduct",
              "spec": {
                 "serverless": {
                    "cloud": "aws",
                    "region": "us-east-1"
                 }
              }
           }'
  ```

  ```bash CLI theme={null}
  # Target the project where you want to create the index.
  pc target -o "example-org" -p "example-project"
  # Create the index.
  pc index create \
    --name "standard-sparse-cli" \
    --vector_type "sparse" \
    --metric "dotproduct" \
    --cloud "aws" \
    --region "us-east-1" \
    --tags "environment=development"
  ```
</CodeGroup>

## Create an index from a backup

You can restore an index from a backup, regardless of whether it stores dense or sparse vectors. For more details, see [Restore an index](/guides/manage-data/restore-an-index).

## Metadata indexing

<Warning>
  This feature is in [early access](/release-notes/feature-availability) and available only on the `2025-10` version of the API. The CLI does not yet support this feature.
</Warning>

Pinecone indexes all metadata fields by default. However, large amounts of metadata can cause slower [index building](/guides/get-started/database-architecture#index-builder) as well as slower [query execution](/guides/get-started/database-architecture#query-executors), particularly when data is not cached in a query executor's memory and local SSD and must be fetched from object storage.

To prevent performance issues due to excessive metadata, you can limit metadata indexing to the fields that you plan to use for [query filtering](/guides/search/filter-by-metadata).

### Set metadata indexing

You can set metadata indexing during index creation or [namespace creation](/reference/api/2025-10/data-plane/createnamespace):

* Index-level metadata indexing rules apply to all namespaces that don't have explicit metadata indexing rules.
* Namespace-level metadata indexing rules overrides index-level metadata indexing rules.

For example, let's say you want to store records that represent chunks of a document, with each record containing many metadata fields. Since you plan to use only a few of the metadata fields to filter queries, you would specify the metadata fields to index as follows.

<Warning>
  Metadata indexing cannot be changed after index or namespace creation.
</Warning>

<CodeGroup>
  ```shell Index-level metadata indexing theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"

  curl "https://api.pinecone.io/indexes" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2025-10" \
    -d '{
          "name": "example-index-metadata",
          "vector_type": "dense",
          "dimension": 1536,
          "metric": "cosine",
          "spec": {
            "serverless": {
              "cloud": "aws",
              "region": "us-east-1",
              "schema": {
                "fields": {
                  "document_id": {
                    "filterable": true
                  },
                  "document_title": {
                    "filterable": true
                  },
                  "chunk_number": {
                    "filterable": true
                  },
                  "document_url": {
                    "filterable": true
                  },
                  "created_at": {
                    "filterable": true
                  }
                }
              }
            }
          },
          "deletion_protection": "disabled"
        }'
  ```

  ```shell Namespace-level metadata indexing theme={null}
  # To learn how to get the unique host for an index,
  # see https://docs.pinecone.io/guides/manage-data/target-an-index
  PINECONE_API_KEY="YOUR_API_KEY"
  INDEX_HOST="INDEX_HOST"

  curl "https://$INDEX_HOST/namespaces" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2025-10" \
    -d '{
          "name": "example-namespace",
          "schema": {
            "fields": {
              "document_id": {
                "filterable": true
              },
              "document_title": {
                "filterable": true
              },
              "chunk_number": {
                "filterable": true
              },
              "document_url": {
                "filterable": true
              },
              "created_at": {
                "filterable": true
              }
            }
          }
        }'
  ```
</CodeGroup>

### Check metadata indexing

To check which metadata fields are indexed, you can describe the index or namespace:

<CodeGroup>
  ```shell Describe index theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"

  curl -X GET "https://api.pinecone.io/indexes/example-index-metadata" \
       -H "Api-Key: $PINECONE_API_KEY" \
       -H "X-Pinecone-Api-Version: 2025-10"
  ```

  ```shell Describe namespace theme={null}
  # To learn how to get the unique host for an index,
  # see https://docs.pinecone.io/guides/manage-data/target-an-index
  PINECONE_API_KEY="YOUR_API_KEY"
  INDEX_HOST="INDEX_HOST"

  curl -X GET "https://$INDEX_HOST/namespaces/example-namespace" \
       -H "Api-Key: $PINECONE_API_KEY" \
       -H "X-Pinecone-Api-Version: 2025-10"
  ```
</CodeGroup>

The response includes the `schema` object with the names of the metadata fields explicitly indexed during index or namespace creation.

<Note>
  The response does not include unindexed metadata fields or metadata fields indexed by default.
</Note>

<CodeGroup>
  ```json Describe index theme={null}
  {
    "id": "751ab850-6e61-4f92-bd23-fa129803d207",
    "vector_type": "dense",
    "name": "example-index",
    "metric": "cosine",
    "dimension": 1536,
    "status": {
      "ready": false,
      "state": "Initializing"
    },
    "host": "example-index-fa77d8e.svc.aped-4627-b74a.pinecone.io",
    "spec": {
      "serverless": {
        "region": "us-east-1",
        "cloud": "aws",
        "read_capacity": {
          "mode": "OnDemand",
          "status": "Ready"
        },
        "schema": {
          "fields": {
            "document_id": {
              "filterable": true
            },
            "document_title": {
              "filterable": true
            },
            "created_at": {
              "filterable": true
            },
            "chunk_number": {
              "filterable": true
            },
            "document_url": {
              "filterable": true
            }
          }
        }
      }
    },
    "deletion_protection": "disabled",
    "tags": null
  }

  ```

  ```json Describe namespace theme={null}
  {
    "name": "example-namespace",
    "record_count": "20000",
    "schema": {
      "fields": {
        "document_title": {
          "filterable": true
        },
        "document_url": {
          "filterable": true
        },
        "chunk_number": {
          "filterable": true
        },
        "document_id": {
          "filterable": true
        },
        "created_at": {
          "filterable": true
        }
      }
    }
  }
  ```
</CodeGroup>

## Index options

### Cloud regions

When creating an index, you must choose the cloud and region where you want the index to be hosted. The following table lists the available public clouds and regions and the plans that support them:

| Cloud   | Region                       | [Supported plans](https://www.pinecone.io/pricing/) | [Availability phase](/release-notes/feature-availability) |
| ------- | ---------------------------- | --------------------------------------------------- | --------------------------------------------------------- |
| `aws`   | `us-east-1` (Virginia)       | Starter, Builder, Standard, Enterprise              | General availability                                      |
| `aws`   | `us-west-2` (Oregon)         | Builder, Standard, Enterprise                       | General availability                                      |
| `aws`   | `eu-west-1` (Ireland)        | Builder, Standard, Enterprise                       | General availability                                      |
| `aws`   | `eu-central-1` (Frankfurt)   | Builder, Standard, Enterprise                       | General availability                                      |
| `aws`   | `ap-southeast-1` (Singapore) | Builder, Standard, Enterprise                       | General availability                                      |
| `gcp`   | `us-central1` (Iowa)         | Builder, Standard, Enterprise                       | General availability                                      |
| `gcp`   | `europe-west4` (Netherlands) | Builder, Standard, Enterprise                       | General availability                                      |
| `azure` | `eastus2` (Virginia)         | Builder, Standard, Enterprise                       | General availability                                      |

The cloud and region cannot be changed after a serverless index is created.

<Note>
  On the Starter plan, you can create serverless indexes in the `us-east-1` region of AWS only. To create indexes in other regions, [upgrade to the Builder, Standard, or Enterprise plan](/guides/organizations/manage-billing/upgrade-billing-plan).
</Note>

### Similarity metrics

When creating an index that stores dense vectors, you can choose from the following similarity metrics. For the most accurate results, choose the similarity metric used to train the embedding model for your vectors. For more information, see [Vector Similarity Explained](https://www.pinecone.io/learn/vector-similarity/).

<Note>Indexes that store [sparse vectors](#sparse-indexes) must use the `dotproduct` metric.</Note>

<AccordionGroup>
  <Accordion title="Euclidean">
    Querying indexes with this metric returns a similarity score equal to the squared Euclidean distance between the result and query vectors.

    This metric calculates the square of the distance between two data points in a plane. It is one of the most commonly used distance metrics. For an example, see our [IT threat detection example](https://colab.research.google.com/github/pinecone-io/examples/blob/master/docs/it-threat-detection.ipynb).

    When you use `metric='euclidean'`, the most similar results are those with the **lowest similarity score**.
  </Accordion>

  <Accordion title="Cosine">
    This is often used to find similarities between different documents. The advantage is that the scores are normalized to \[-1,1] range. For an example, see our [generative question answering example](https://colab.research.google.com/github/pinecone-io/examples/blob/master/docs/gen-qa-openai.ipynb).
  </Accordion>

  <Accordion title="Dotproduct">
    This is used to multiply two vectors. You can use it to tell us how similar the two vectors are. The more positive the answer is, the closer the two vectors are in terms of their directions. For an example, see our [semantic search example](https://colab.research.google.com/github/pinecone-io/examples/blob/master/docs/semantic-search.ipynb).
  </Accordion>
</AccordionGroup>

### Embedding models

[Dense vectors](/guides/get-started/concepts#dense-vector) and [sparse vectors](/guides/get-started/concepts#sparse-vector) are the basic units of data in Pinecone and what Pinecone was specially designed to store and work with. Dense vectors represents the semantics of data such as text, images, and audio recordings, while sparse vectors represent documents or queries in a way that captures keyword information.

To transform data into vector format, you use an embedding model. Pinecone hosts several embedding models so it's easy to manage your vector storage and search process on a single platform. You can use a hosted model to embed your data as an integrated part of upserting and querying, or you can use a hosted model to embed your data as a standalone operation.

The following embedding models are hosted by Pinecone.

<Note>
  To understand how cost is calculated for embedding, see [Embedding cost](/guides/manage-cost/understanding-cost#embedding). To get model details via the API, see [List models](/reference/api/latest/inference/list_models) and [Describe a model](/reference/api/latest/inference/describe_model).
</Note>

#### multilingual-e5-large

[`multilingual-e5-large`](/models/multilingual-e5-large) is an efficient dense embedding model trained on a mixture of multilingual datasets. It works well on messy data and short queries expected to return medium-length passages of text (1-2 paragraphs).

**Details**

* Vector type: Dense
* Modality: Text
* Dimension: 1024
* Recommended similarity metric: Cosine
* Max sequence length: 507 tokens
* Max batch size: 96 sequences

For rate limits, see [Embedding tokens per minute](/reference/api/database-limits#embedding-tokens-per-minute-per-model) and [Embedding tokens per month](/reference/api/database-limits#embedding-tokens-per-month-per-model).

**Parameters**

The `multilingual-e5-large` model supports the following parameters:

| Parameter    | Type   | Required/Optional | Description                                                                                                                                                                                                                                    | Default |
| :----------- | :----- | :---------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------ |
| `input_type` | string | Required          | The type of input data. Accepted values: `query` or `passage`.                                                                                                                                                                                 |         |
| `truncate`   | string | Optional          | How to handle inputs longer than those supported by the model. Accepted values: `END` or `NONE`.<br /><br />`END` truncates the input sequence at the input token limit. `NONE` returns an error when the input exceeds the input token limit. | `END`   |

#### llama-text-embed-v2

[`llama-text-embed-v2`](/models/llama-text-embed-v2) is a high-performance dense embedding model optimized for text retrieval and ranking tasks. It is trained on a diverse range of text corpora and provides strong performance on longer passages and structured documents.

**Details**

* Vector type: Dense
* Modality: Text
* Dimension: 1024 (default), 2048, 768, 512, 384
* Recommended similarity metric: Cosine
* Max sequence length: 2048 tokens
* Max batch size: 96 sequences

For rate limits, see [Embedding tokens per minute](/reference/api/database-limits#embedding-tokens-per-minute-per-model) and [Embedding tokens per month](/reference/api/database-limits#embedding-tokens-per-month-per-model).

**Parameters**

The `llama-text-embed-v2` model supports the following parameters:

| Parameter    | Type    | Required/Optional | Description                                                                                                                                                                                                                                    | Default |
| :----------- | :------ | :---------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------ |
| `input_type` | string  | Required          | The type of input data. Accepted values: `query` or `passage`.                                                                                                                                                                                 |         |
| `truncate`   | string  | Optional          | How to handle inputs longer than those supported by the model. Accepted values: `END` or `NONE`.<br /><br />`END` truncates the input sequence at the input token limit. `NONE` returns an error when the input exceeds the input token limit. | `END`   |
| `dimension`  | integer | Optional          | Dimension of the vector to return.                                                                                                                                                                                                             | 1024    |

#### pinecone-sparse-english-v0

[`pinecone-sparse-english-v0`](/models/pinecone-sparse-english-v0) is a sparse embedding model for converting text to [sparse vectors](/guides/get-started/concepts#sparse-vector) for [sparse-vector lexical search](/guides/search/lexical-search) or hybrid search. Built on the innovations of the [DeepImpact architecture](https://arxiv.org/pdf/2104.12016), the model directly estimates the lexical importance of tokens by leveraging their context, unlike traditional retrieval models like BM25, which rely solely on term frequency.

**Details**

* Vector type: Sparse
* Modality: Text
* Recommended similarity metric: Dotproduct
* Max sequence length: 512 or 2048
* Max batch size: 96 sequences

For rate limits, see [Embedding tokens per minute](/reference/api/database-limits#embedding-tokens-per-minute-per-model) and [Embedding tokens per month](/reference/api/database-limits#embedding-tokens-per-month-per-model).

**Parameters**

The `pinecone-sparse-english-v0` model supports the following parameters:

| Parameter                 | Type    | Required/Optional | Description                                                                                                                                                                                                                                                                    | Default |
| :------------------------ | :------ | :---------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------ |
| `input_type`              | string  | Required          | The type of input data. Accepted values: `query` or `passage`.                                                                                                                                                                                                                 |         |
| `max_tokens_per_sequence` | integer | Optional          | Maximum number of tokens to embed. Accepted values: `512` or `2048`.                                                                                                                                                                                                           | `512`   |
| `truncate`                | string  | Optional          | How to handle inputs longer than those supported by the model. Accepted values: `END` or `NONE`.<br /><br />`END` truncates the input sequence at the the `max_tokens_per_sequence` limit. `NONE` returns an error when the input exceeds the `max_tokens_per_sequence` limit. | `END`   |
| `return_tokens`           | boolean | Optional          | Whether to return the string tokens.                                                                                                                                                                                                                                           | `false` |


# Data ingestion overview
Source: https://docs.pinecone.io/guides/index-data/data-ingestion-overview

Compare data ingestion options in Pinecone: bulk import from object storage, upsert operations, and hosted embedding via the Inference API.

<Tip>
  To control costs when ingesting large datasets (10,000,000+ records), use [import](/guides/index-data/import-data) instead of upsert.
</Tip>

## Import from object storage

[Importing from object storage](/guides/index-data/import-data) is the most efficient and cost-effective method to load large numbers of records into an index. You store your data as Parquet files in object storage, integrate your object storage with Pinecone, and then start an asynchronous, long-running operation that imports and indexes your records.

<Note>
  This feature is in [public preview](/release-notes/feature-availability) and available only on [Standard and Enterprise plans](https://www.pinecone.io/pricing/).
</Note>

## Upsert

For ongoing ingestion into an index, either one record at a time or in batches, use the [upsert](/guides/index-data/upsert-data) operation. [Batch upserting](/guides/index-data/upsert-data#upsert-in-batches) can improve throughput performance and is a good option for larger numbers of records if you cannot work around import's current [limitations](/guides/index-data/import-data#import-limits).

## When you only need embeddings

Import and upsert move vectors into Pinecone. For workflows where you only need vectors from hosted models (for example, to embed offline and upsert later), use the Inference API as follows:

You can call the [`embed` operation](/reference/api/latest/inference/generate-embeddings) through Pinecone Inference to turn text into vectors without writing to an index. That differs from [`upsert_records`](/reference/api/latest/data-plane/upsert_records) on an index with integrated embedding, where each request embeds and stores records in one step. To see how embedding consumption appears in billing and usage reports, see [Embedding tokens](/guides/manage-cost/monitor-usage-and-costs#embedding-tokens).

## Ingestion cost

* To understand how cost is calculated for imports, see [Import cost](/guides/manage-cost/understanding-cost#imports).
* To understand how cost is calculated for upserts, see [Write unit pricing](/guides/manage-cost/understanding-cost#write-units).
* For up-to-date pricing information, see [Pricing](https://www.pinecone.io/pricing/).

## Data freshness

Pinecone is eventually consistent, so there can be a slight delay before new or changed records are visible to queries. You can view index stats to [check data freshness](/guides/index-data/check-data-freshness).


# Data modeling
Source: https://docs.pinecone.io/guides/index-data/data-modeling

Model your data in Pinecone using documents with dense_vector, sparse_vector, full-text string, and metadata fields for efficient retrieval.

Pinecone has two ways to model your data, and the choice is made when you create the index: an index created with a document schema holds documents, while an index created with a dense or sparse vector type holds records. Both hold a unique `_id` and optional metadata and live in [namespaces](/guides/index-data/indexing-overview#namespaces); they differ in how many ranking signals a single item can carry and which API you call. Both are fully supported.

* **[Documents](#documents)** are the unit of data in an index with a **document schema**, the model behind [full-text search](/guides/search/full-text-search). A document is a JSON object that can carry text fields (ranked with BM25 and Lucene queries), a dense vector, a sparse vector, and metadata in a single index, and you pick the ranking signal per query with `score_by`. Use documents for text-first search or any workload that needs more than one ranking signal in one index.
* **[Records](#records)** are the unit of data for [indexes with dense vectors](/guides/get-started/concepts#index-with-dense-vectors) and [indexes with sparse vectors](/guides/get-started/concepts#index-with-sparse-vectors), the vector API. A record carries one vector (or raw text for Pinecone to embed) plus metadata. Use records for vector-only workloads.

## Documents

A document is the unit of data in an index with a document schema — a JSON object with a required `_id` field, the ranking fields declared in the index's schema, and any number of metadata fields. Documents support multiple field types in a single record: a `dense_vector` field (for [semantic search](/guides/search/semantic-search)), a `sparse_vector` field (for [sparse-vector lexical search](/guides/search/lexical-search)), one or more `string` fields with `full_text_search` enabled (for [full-text search](/guides/search/full-text-search) with BM25 and Lucene queries), plus any metadata you upsert alongside them.

The schema, declared at index creation, tells Pinecone how to rank each ranking field. Schema field types:

* `dense_vector` — indexed for ANN similarity search.
* `sparse_vector` — indexed for sparse-vector lexical search.
* `string` with a nested `full_text_search` config object (`{}` enables with all defaults; optional sub-fields: `language`, `stemming`, `stop_words`) — indexed for **BM25** ranking and Lucene queries. Lowercasing and the token length cap are server-applied and cannot be overridden.

Metadata fields are not declared in the schema. Any field you upsert that is not declared in the schema is stored on the document, returned via `include_fields`, and automatically indexed for filtering. Pinecone infers the metadata field type from the values you upsert: strings, numbers (floating point), booleans, and arrays of strings are all supported.

Document fields can hold structured values: a metadata `string_list` field holds an array of strings; a `dense_vector` field holds an array of floats; a `sparse_vector` field is an object with two parallel arrays — `indices` (token positions) and `values` (token weights).

A schema can declare up to 100 `string` fields with `full_text_search` enabled, but at most one `dense_vector` field and at most one `sparse_vector` field per index.

Example document for an index with `title`, `body`, `embedding`, and `category` fields:

```json theme={null}
{
  "_id": "document1#chunk1",
  "title": "Introduction to Vector Databases",
  "body": "First chunk of the document content...",
  "embedding": [0.0236, -0.0329, ..., -0.0104, 0.0086],
  "category": "tutorial"
}
```

Field-name rules:

* Must be unique, non-empty strings.
* Must not start with `_` (reserved for system-managed fields like `_id` and `_score`) or `$` (reserved for filter operators).
* Limited to 64 bytes.

For the full schema reference (language and analyzer options, multi-field schemas, scoring methods), see [Full-text search](/guides/search/full-text-search).

<Note>
  **Chunking granularity.** A document is the unit of retrieval — `top_k` and `_score` are computed per document, not per sub-section. In public preview, Pinecone does not split a single document into multiple in-document chunks at index time. If your source content is longer than what you want to retrieve as one hit (a long article, a PDF, a transcript), do the chunking in your application before upsert and store each chunk as its own document, with an ID like `document1#chunk1`, `document1#chunk2`, and a metadata field that ties chunks back to the parent document for grouping at query time.
</Note>

### Schema patterns

The same document model supports several common schema shapes. Pick the one that matches the signal you want to rank by, and plan your fields up front: in public preview, schema migration is not supported after index creation. Filters are deterministic per document and apply before scoring; choose your hard yes/no constraints (including text-match operators on FTS-enabled `string` fields) first, then pick a `score_by` method to rank whatever remains. See [Filters vs. scoring](/guides/search/full-text-search#filters-vs-scoring).

<Note>
  The Python snippets in each accordion below assume an initialized client and the schema-builder import:

  ```python Python theme={null}
  from pinecone import Pinecone
  from pinecone.preview import SchemaBuilder

  pc = Pinecone(api_key="YOUR_API_KEY")
  ```

  Each accordion shows the pattern-specific schema, an example document, and a search snippet. The control-plane (`pc.preview.indexes.create(...)`) and data-plane (`index = pc.preview.index(name=...)`) calls in the snippets reuse this `pc`.
</Note>

<AccordionGroup>
  <Accordion title="Single text field — keyword search only (FTS)">
    Use when you want BM25 keyword ranking on one piece of text per document (a review body, a support ticket, a product description) and you don't have embeddings to manage.

    ```python Python theme={null}
    from pinecone.preview import SchemaBuilder

    schema = (
        SchemaBuilder()
        .add_string_field("review_text", full_text_search={"language": "en"})
        .build()
    )

    pc.preview.indexes.create(name="book-reviews", schema=schema)
    ```

    A document upserted into this index looks like:

    ```json theme={null}
    {
      "_id": "review-1234",
      "review_text": "Beautifully written exploration of contact, communication, and civilization across cosmic distances. The pacing is uneven but the central premise carries you through."
    }
    ```

    Search with a single `text` clause (the score\_by `type`, not a field type — this clause runs BM25 ranking on the named string field):

    ```python Python theme={null}
    index.documents.search(
        namespace="reviews",
        top_k=10,
        score_by=[{"type": "text", "field": "review_text", "query": "civilization"}],
    )
    ```

    See [Full-text search](/guides/search/full-text-search).
  </Accordion>

  <Accordion title="Multi-field FTS — score across two text fields (e.g. body + summary)">
    Use when a document has more than one piece of text that should both contribute to ranking — for example, a long `review_text` plus a short `review_summary`. Pinecone combines the per-field BM25 scores into one ranking per document.

    ```python Python theme={null}
    schema = (
        SchemaBuilder()
        .add_string_field("review_text", full_text_search={"language": "en"})
        .add_string_field("review_summary", full_text_search={"language": "en"})
        .build()
    )

    pc.preview.indexes.create(name="book-reviews-multi", schema=schema)
    ```

    A document upserted into this index looks like:

    ```json theme={null}
    {
      "_id": "review-1234",
      "review_text": "Beautifully written exploration of contact, communication, and civilization across cosmic distances. The pacing is uneven but the central premise carries you through.",
      "review_summary": "Monumental science fiction with uneven pacing",
      "category": "science-fiction",
      "rating": 4.5
    }
    ```

    `category` and `rating` are not declared in the schema — they're upserted as metadata, automatically indexed for filtering, and usable in `filter` expressions.

    Pass two `text` clauses in `score_by`; the server combines them into one ranking, with each contributing field weighted equally in `2026-01.alpha`.

    ```python Python theme={null}
    index = pc.preview.index(name="book-reviews-multi")

    index.documents.search(
        namespace="reviews",
        top_k=5,
        score_by=[
            {"type": "text", "field": "review_text",    "query": "disappointing"},
            {"type": "text", "field": "review_summary", "query": "Disappointing"},
        ],
        include_fields=["*"],
    )
    ```
  </Accordion>

  <Accordion title="Dense + FTS — semantic and keyword in one index">
    Most workloads that combine semantic ranking with keyword matching reach for this pattern: rank by dense (or sparse) similarity, restricted to documents that contain a specific term or phrase. Common examples include semantic search over patents, regulatory filings, internal knowledge bases, or other technical literature where the right answer must contain a specific term. A single schema can include one `dense_vector` field plus any number of FTS-enabled string fields:

    ```python Python theme={null}
    schema = (
        SchemaBuilder()
        .add_string_field("book_title", full_text_search={"language": "en"})
        .add_string_field("review_text", full_text_search={"language": "en"})
        .add_dense_vector_field("review_embedding", dimension=1024, metric="cosine")
        .build()
    )

    pc.preview.indexes.create(name="book-reviews-dense", schema=schema)
    ```

    A document upserted into this index looks like:

    ```json theme={null}
    {
      "_id": "review-1234",
      "book_title": "The Three-Body Problem",
      "review_text": "Beautifully written exploration of contact, communication, and civilization across cosmic distances.",
      "review_embedding": [0.012, -0.087, 0.153, ...]
    }
    ```

    `review_embedding` is a 1024-dim list of floats produced by your dense embedding model. Use the same model at query time so the query vector lives in the same space.

    A single search request ranks by one scoring type. With this schema you have two query options:

    **Option A — dense ranking restricted by a text-match filter** (the most common hybrid pattern):

    ```python Python theme={null}
    index = pc.preview.index(name="book-reviews-dense")

    # query_embedding is a 1024-dim list of floats from your embedding model.
    query_embedding = embed("beautifully written, hard sci-fi")

    index.documents.search(
        namespace="reviews",
        top_k=5,
        score_by=[
            {"type": "dense_vector", "field": "review_embedding", "values": query_embedding},
        ],
        filter={"review_text": {"$match_phrase": "beautifully written"}},
    )
    ```

    **Option B — run BM25 and dense searches separately and merge client-side** (when you want both signals to contribute to ranking, e.g. via [reciprocal rank fusion](/guides/search/reciprocal-rank-fusion)):

    ```python Python theme={null}
    dense_hits = index.documents.search(
        namespace="reviews", top_k=50,
        score_by=[{"type": "dense_vector", "field": "review_embedding", "values": query_embedding}],
    )
    bm25_hits = index.documents.search(
        namespace="reviews", top_k=50,
        score_by=[{"type": "text", "field": "review_text", "query": "beautifully written"}],
    )
    # Merge dense_hits + bm25_hits in your application (e.g. RRF) to produce final ranking.
    ```

    See [Hybrid search](/guides/search/hybrid-search) for a fuller discussion.

    <Tip>
      The `dense_vector` field's source content is independent of the FTS-enabled `string` fields it sits alongside. You can embed images (e.g., with a multimodal model like Gemini Embedding 2 or a CLIP-style model) and pair them with FTS-enabled `string` fields holding captions, geography, or taxonomy — then query the image vector with a text description and restrict matches with FTS filters on those `string` fields. The schema doesn't constrain what the dense vector represents; it just stores a vector of the declared dimension.
    </Tip>
  </Accordion>

  <Accordion title="Multi-signal index — dense + sparse + FTS in one schema">
    Use when a single document is best described by more than one ranking signal — for example, a video catalog where each item has frame embeddings (dense), auto-generated captions you've encoded as sparse vectors (sparse), and a transcript text field (BM25/Lucene). One schema declares all three; you pick the ranking signal per query with `score_by`. No second index, no cross-index linkage to maintain.

    ```python Python theme={null}
    schema = (
        SchemaBuilder()
        .add_dense_vector_field("frame_embedding", dimension=1024, metric="cosine")
        .add_sparse_vector_field("caption_sparse")
        .add_string_field("transcript", full_text_search={"language": "en"})
        .build()
    )

    pc.preview.indexes.create(name="video-catalog", schema=schema)
    ```

    A `language` field upserted alongside these ranking fields is treated as metadata: stored on the document, returned via `include_fields`, and auto-indexed for filtering.

    A document upserted into this index looks like:

    ```json theme={null}
    {
      "_id": "video-7890#scene-3",
      "frame_embedding": [0.012, -0.087, 0.153, ...],
      "caption_sparse": {
        "indices": [42, 1077, 9821],
        "values":  [0.41, 0.33, 0.18]
      },
      "transcript": "I think we should go now before it gets dark.",
      "language": "en"
    }
    ```

    `frame_embedding` is a 1024-dim list of floats from your dense vision model. `caption_sparse` is the output of your sparse encoder — an object with parallel `indices` (token IDs) and `values` (token weights) arrays.

    The same index supports three different query shapes. All three assume:

    ```python Python theme={null}
    index = pc.preview.index(name="video-catalog")

    # Replace with the outputs of your encoders.
    query_embedding = embed_image(query_image)                 # 1024-dim list of floats
    query_sparse    = sparse_encode("scene with a lighthouse") # {"indices": [...], "values": [...]}
    ```

    **Semantic frame search** — rank by visual similarity:

    ```python Python theme={null}
    index.documents.search(
        namespace="videos",
        top_k=10,
        score_by=[{"type": "dense_vector", "field": "frame_embedding", "values": query_embedding}],
    )
    ```

    **Caption lexical search** — rank by sparse-vector lexical similarity over your encoded captions:

    ```python Python theme={null}
    index.documents.search(
        namespace="videos",
        top_k=10,
        score_by=[{"type": "sparse_vector", "field": "caption_sparse", "sparse_values": query_sparse}],
    )
    ```

    **Semantic search restricted to spoken phrase** — semantic frame ranking, narrowed to clips where the transcript contains a specific phrase:

    ```python Python theme={null}
    index.documents.search(
        namespace="videos",
        top_k=10,
        score_by=[{"type": "dense_vector", "field": "frame_embedding", "values": query_embedding}],
        filter={"transcript": {"$match_phrase": "I love you"}},
    )
    ```

    `score_by` selects one ranking signal per request, but every signal stays addressable on the same documents.
  </Accordion>

  <Accordion title="Sparse + dense hybrid — single-vector index (vector API)">
    Use when you're modeling data with the [vector API](#records) (not the document API) and want to combine a sparse and dense vector in one record on a single index. For new document-centric projects with text data, prefer the document-shape Dense + FTS pattern above.

    ```json theme={null}
    {
      "id": "doc1#chunk1",
      "values": [0.0236, -0.0329, ..., -0.0104, 0.0086],
      "sparse_values": {
        "indices": [822745112, 1009084850, ...],
        "values":  [1.7958984, 0.41577148, ...]
      },
      "metadata": { "document_id": "doc1", "chunk_number": 1 }
    }
    ```

    See [Hybrid search](/guides/search/hybrid-search).
  </Accordion>
</AccordionGroup>

## Records

Records are how you model data for [indexes with dense vectors](/guides/get-started/concepts#index-with-dense-vectors) and [indexes with sparse vectors](/guides/get-started/concepts#index-with-sparse-vectors). Each record carries one vector (dense, sparse, or both for single-index hybrid) plus optional metadata, and you can upsert raw text in place of a vector when the index is [integrated with an embedding model](/guides/index-data/create-an-index#embedding-models).

<Tabs>
  <Tab title="Vectors">
    When you upsert pre-generated vectors, each record consists of the following:

    * **ID**: A unique string identifier for the record.
    * **Vector**: A dense vector for [semantic search](/guides/search/semantic-search), a sparse vector for [sparse-vector lexical search](/guides/search/lexical-search), or both for single-index [hybrid search](/guides/search/hybrid-search) (vector API).
    * **Metadata** (optional): A flat JSON document containing key-value pairs with additional information (nested objects are not supported). You can filter by metadata when searching or deleting records.

    <Note>
      When importing data from object storage, records must be in Parquet format. For more details, see [Import data](/guides/index-data/import-data#prepare-your-data).
    </Note>

    Example:

    <CodeGroup>
      ```json Dense theme={null}
      {
        "id": "document1#chunk1", 
        "values": [0.0236663818359375, -0.032989501953125, ..., -0.01041412353515625, 0.0086669921875], 
        "metadata": {
          "document_id": "document1",
          "document_title": "Introduction to Vector Databases",
          "chunk_number": 1,
          "chunk_text": "First chunk of the document content...",
          "document_url": "https://example.com/docs/document1",
          "created_at": "2024-01-15",
          "document_type": "tutorial"
        }
      }
      ```

      ```json Sparse theme={null}
      {
        "id": "document1#chunk1", 
        "sparse_values": {
          "values": [1.7958984, 0.41577148, ..., 4.4414062, 3.3554688],
          "indices": [822745112, 1009084850, ..., 3517203014, 3590924191]
        },
        "metadata": {
          "document_id": "document1",
          "document_title": "Introduction to Vector Databases",
          "chunk_number": 1,
          "chunk_text": "First chunk of the document content...",
          "document_url": "https://example.com/docs/document1",
          "created_at": "2024-01-15",
          "document_type": "tutorial"
        }
      }
      ```

      ```json Hybrid theme={null}
      {
        "id": "document1#chunk1", 
        "values": [0.0236663818359375, -0.032989501953125, ..., -0.01041412353515625, 0.0086669921875], 
        "sparse_values": {
          "values": [1.7958984, 0.41577148, ..., 4.4414062, 3.3554688],
          "indices": [822745112, 1009084850, ..., 3517203014, 3590924191]
        },
        "metadata": {
          "document_id": "document1",
          "document_title": "Introduction to Vector Databases",
          "chunk_number": 1,
          "chunk_text": "First chunk of the document content...",
          "document_url": "https://example.com/docs/document1",
          "created_at": "2024-01-15",
          "document_type": "tutorial"
        }
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Text">
    When you upsert raw text for Pinecone to convert to vectors automatically, each record consists of the following:

    * **ID**: A unique string identifier for the record.
    * **Text**: The raw text for Pinecone to convert to a dense vector for [semantic search](/guides/search/semantic-search) or a sparse vector for [sparse-vector lexical search](/guides/search/lexical-search), depending on the [embedding model](/guides/index-data/create-an-index#embedding-models) integrated with the index. This field name must match the `embed.field_map` defined in the index.
    * **Metadata** (optional): All additional fields are stored as record metadata. You can filter by metadata when searching or deleting records.

    <Note>
      Upserting raw text is supported only for [indexes with integrated embedding](/guides/index-data/indexing-overview#vector-embedding).
    </Note>

    Example:

    ```json theme={null}
    {
      "_id": "document1#chunk1", 
      "chunk_text": "First chunk of the document content...", // Text to convert to a vector. 
      "document_id": "document1", // This and subsequent fields stored as metadata. 
      "document_title": "Introduction to Vector Databases",
      "chunk_number": 1,
      "document_url": "https://example.com/docs/document1", 
      "created_at": "2024-01-15",
      "document_type": "tutorial"
    }
    ```
  </Tab>
</Tabs>

## Use structured IDs

Use a structured, human-readable format for record IDs, including ID prefixes that reflect the type of data you're storing, for example:

* **Document chunks**: `document_id#chunk_number`
* **User data**: `user_id#data_type#item_id`
* **Multi-tenant data**: `tenant_id#document_id#chunk_id`

Choose a delimiter for your ID prefixes that won't appear elsewhere in your IDs. Common patterns include:

* `document1#chunk1` - Using hash delimiter
* `document1_chunk1` - Using underscore delimiter
* `document1:chunk1` - Using colon delimiter

Structuring IDs in this way provides several advantages:

* **Efficiency**: Applications can quickly identify which record it should operate on.
* **Clarity**: Developers can easily understand what they're looking at when examining records.
* **Flexibility**: ID prefixes enable list operations for fetching and updating records.

## Include metadata

Include [metadata key-value pairs](/guides/index-data/indexing-overview#metadata) that support your application's key operations, for example:

* **Enable query-time filtering**: Add fields for time ranges, categories, or other criteria for [filtering searches for increased accuracy and relevance](/guides/search/filter-by-metadata).
* **Link related chunks**: Use fields like `document_id` and `chunk_number` to keep track of related records and enable efficient [chunk deletion](#delete-chunks) and [document updates](#update-an-entire-document).
* **Link back to original data**: Include `chunk_text` or `document_url` for traceability and user display.

Metadata keys must be strings, and metadata values must be one of the following data types:

* String
* Number (stored as a 64-bit floating point)
* Boolean (true, false)
* List of strings

<Note>
  Pinecone supports 40 KB of metadata per record.
</Note>

## Example

This example demonstrates how to manage document chunks in Pinecone using structured IDs and comprehensive metadata. It covers the complete lifecycle of chunked documents: upserting, searching, fetching, updating, and deleting chunks, and updating an entire document.

### Upsert chunks

When [upserting](/guides/index-data/upsert-data) documents that have been split into chunks, combine structured IDs with comprehensive metadata:

<Tabs>
  <Tab title="Upsert text">
    <Note>
      Upserting raw text is supported only for [indexes with integrated embedding](/guides/index-data/create-an-index#integrated-embedding).
    </Note>

    ```python Python theme={null}
    from pinecone.grpc import PineconeGRPC as Pinecone

    pc = Pinecone(api_key="YOUR_API_KEY")

    # To get the unique host for an index, 
    # see https://docs.pinecone.io/guides/manage-data/target-an-index
    index = pc.Index(host="INDEX_HOST")

    index.upsert_records(
      "example-namespace",
      [
        {
          "_id": "document1#chunk1", 
          "chunk_text": "First chunk of the document content...",
          "document_id": "document1",
          "document_title": "Introduction to Vector Databases",
          "chunk_number": 1,
          "document_url": "https://example.com/docs/document1",
          "created_at": "2024-01-15",
          "document_type": "tutorial"
        },
        {
          "_id": "document1#chunk2", 
          "chunk_text": "Second chunk of the document content...",
          "document_id": "document1",
          "document_title": "Introduction to Vector Databases", 
          "chunk_number": 2,
          "document_url": "https://example.com/docs/document1",
          "created_at": "2024-01-15",
          "document_type": "tutorial"
        },
        {
          "_id": "document1#chunk3", 
          "chunk_text": "Third chunk of the document content...",
          "document_id": "document1",
          "document_title": "Introduction to Vector Databases",
          "chunk_number": 3, 
          "document_url": "https://example.com/docs/document1",
          "created_at": "2024-01-15",
          "document_type": "tutorial"
        },
      ]
    )
    ```
  </Tab>

  <Tab title="Upsert vectors">
    ```python Python theme={null}
    from pinecone.grpc import PineconeGRPC as Pinecone

    pc = Pinecone(api_key="YOUR_API_KEY")

    # To get the unique host for an index, 
    # see https://docs.pinecone.io/guides/manage-data/target-an-index
    index = pc.Index(host="INDEX_HOST")

    index.upsert(
      namespace="example-namespace",
      vectors=[
        {
          "id": "document1#chunk1", 
          "values": [0.0236663818359375, -0.032989501953125, ..., -0.01041412353515625, 0.0086669921875], 
          "metadata": {
            "document_id": "document1",
            "document_title": "Introduction to Vector Databases",
            "chunk_number": 1,
            "chunk_text": "First chunk of the document content...",
            "document_url": "https://example.com/docs/document1",
            "created_at": "2024-01-15",
            "document_type": "tutorial"
          }
        },
        {
          "id": "document1#chunk2", 
          "values": [-0.0412445068359375, 0.028839111328125, ..., 0.01953125, -0.0174560546875],
          "metadata": {
            "document_id": "document1",
            "document_title": "Introduction to Vector Databases", 
            "chunk_number": 2,
            "chunk_text": "Second chunk of the document content...",
            "document_url": "https://example.com/docs/document1",
            "created_at": "2024-01-15",
            "document_type": "tutorial"
          }
        },
        {
          "id": "document1#chunk3", 
          "values": [0.0512237548828125, 0.041656494140625, ..., 0.02130126953125, -0.0394287109375],
          "metadata": {
            "document_id": "document1",
            "document_title": "Introduction to Vector Databases",
            "chunk_number": 3, 
            "chunk_text": "Third chunk of the document content...",
            "document_url": "https://example.com/docs/document1",
            "created_at": "2024-01-15",
            "document_type": "tutorial"
          }
        }
      ]
    )
    ```
  </Tab>
</Tabs>

### Search chunks

To search the chunks of a document, use a [metadata filter expression](/guides/search/filter-by-metadata#metadata-filter-expressions) that limits the search appropriately:

<Tabs>
  <Tab title="Search with text">
    <Note>
      Searching with text is supported only for [indexes with integrated embedding](/guides/index-data/create-an-index#integrated-embedding).
    </Note>

    ```python Python theme={null}
    from pinecone import Pinecone

    pc = Pinecone(api_key="YOUR_API_KEY")

    # To get the unique host for an index, 
    # see https://docs.pinecone.io/guides/manage-data/target-an-index
    index = pc.Index(host="INDEX_HOST")

    filtered_results = index.search(
        namespace="example-namespace", 
        query={
            "inputs": {"text": "What is a vector database?"}, 
            "top_k": 3,
            "filter": {"document_id": "document1"}
        },
        fields=["chunk_text"]
    )

    print(filtered_results)
    ```
  </Tab>

  <Tab title="Search with a vector">
    ```python Python theme={null}
    from pinecone.grpc import PineconeGRPC as Pinecone

    pc = Pinecone(api_key="YOUR_API_KEY")

    # To get the unique host for an index, 
    # see https://docs.pinecone.io/guides/manage-data/target-an-index
    index = pc.Index(host="INDEX_HOST")

    filtered_results = index.query(
        namespace="example-namespace",
        vector=[0.0236663818359375,-0.032989501953125, ..., -0.01041412353515625,0.0086669921875], 
        top_k=3,
        filter={
            "document_id": {"$eq": "document1"}
        },
        include_metadata=True,
        include_values=False
    )

    print(filtered_results)
    ```
  </Tab>
</Tabs>

### Fetch chunks

To retrieve all chunks for a specific document, first [list the record IDs](/guides/manage-data/list-record-ids) using the document prefix, and then [fetch](/guides/manage-data/fetch-data) the complete records:

```python Python theme={null}
from pinecone.grpc import PineconeGRPC as Pinecone

pc = Pinecone(api_key="YOUR_API_KEY")

# To get the unique host for an index, 
# see https://docs.pinecone.io/guides/manage-data/target-an-index
index = pc.Index(host="INDEX_HOST")

# List all chunks for document1 using ID prefix
chunk_ids = []
for record_id in index.list(prefix='document1#', namespace='example-namespace'):
    chunk_ids.append(record_id)

print(f"Found {len(chunk_ids)} chunks for document1")

# Fetch the complete records by ID
if chunk_ids:
    records = index.fetch(ids=chunk_ids, namespace='example-namespace')
    
    for record_id, record_data in records['vectors'].items():
        print(f"Chunk ID: {record_id}")
        print(f"Chunk text: {record_data['metadata']['chunk_text']}")
        # Process the vector values and metadata as needed
```

<Note>
  Pinecone is [eventually consistent](/guides/index-data/check-data-freshness), so it's possible that a write (upsert, update, or delete) followed immediately by a read (query, list, or fetch) may not return the latest version of the data. If your use case requires retrieving data immediately, consider implementing a small delay or [retry logic](/guides/production/error-handling#implement-retry-logic) after writes.
</Note>

### Update chunks

To [update](/guides/manage-data/update-data) specific chunks within a document, first list the chunk IDs, and then update individual records:

```python Python theme={null}
from pinecone.grpc import PineconeGRPC as Pinecone

pc = Pinecone(api_key="YOUR_API_KEY")

# To get the unique host for an index, 
# see https://docs.pinecone.io/guides/manage-data/target-an-index
index = pc.Index(host="INDEX_HOST")

# List all chunks for document1
chunk_ids = []
for record_id in index.list(prefix='document1#', namespace='example-namespace'):
    chunk_ids.append(record_id)

# Update specific chunks (e.g., update chunk 2)
if 'document1#chunk2' in chunk_ids:
    new_vector = ...  # from your embedding model
    index.update(
        id='document1#chunk2',
        values=new_vector,
        set_metadata={
            "document_id": "document1",
            "document_title": "Introduction to Vector Databases - Revised",
            "chunk_number": 2,
            "chunk_text": "Updated second chunk content...",
            "document_url": "https://example.com/docs/document1",
            "created_at": "2024-01-15",
            "updated_at": "2024-02-15",
            "document_type": "tutorial"
        },
        namespace='example-namespace'
    )
    print("Updated chunk 2 successfully")
```

### Delete chunks

To [delete](/guides/manage-data/delete-data#delete-records-by-metadata) chunks of a document, use a [metadata filter expression](/guides/search/filter-by-metadata#metadata-filter-expressions) that limits the deletion appropriately:

```python Python theme={null}
from pinecone.grpc import PineconeGRPC as Pinecone

pc = Pinecone(api_key="YOUR_API_KEY")

# To get the unique host for an index, 
# see https://docs.pinecone.io/guides/manage-data/target-an-index
index = pc.Index(host="INDEX_HOST")

# Delete chunks 1 and 3
index.delete(
    namespace="example-namespace",
    filter={
        "document_id": {"$eq": "document1"},
        "chunk_number": {"$in": [1, 3]}
    }
)

# Delete all chunks for a document
index.delete(
    namespace="example-namespace",
    filter={
        "document_id": {"$eq": "document1"}
    }
)
```

### Update an entire document

<Tip>
  If you need to update most of the records in a large namespace, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) for help creating an export to enable a faster and more cost-effective approach.
</Tip>

When the amount of chunks or ordering of chunks for a document changes, the recommended approach is to first [delete all chunks using a metadata filter](/guides/manage-data/delete-data#delete-records-by-metadata), and then [upsert](/guides/index-data/upsert-data) the new chunks:

```python Python theme={null}
from pinecone.grpc import PineconeGRPC as Pinecone

pc = Pinecone(api_key="YOUR_API_KEY")

# To get the unique host for an index, 
# see https://docs.pinecone.io/guides/manage-data/target-an-index
index = pc.Index(host="INDEX_HOST")

# Step 1: Delete all existing chunks for the document
index.delete(
    namespace="example-namespace",
    filter={
        "document_id": {"$eq": "document1"}
    }
)

print("Deleted existing chunks for document1")

# Step 2: Upsert the updated document chunks
chunk1_vector = ...  # from your embedding model
chunk2_vector = ...
index.upsert(
  namespace="example-namespace", 
  vectors=[
    {
      "id": "document1#chunk1",
      "values": chunk1_vector,
      "metadata": {
        "document_id": "document1",
        "document_title": "Introduction to Vector Databases - Updated Edition",
        "chunk_number": 1,
        "chunk_text": "Updated first chunk with new content...",
        "document_url": "https://example.com/docs/document1",
        "created_at": "2024-02-15",
        "document_type": "tutorial",
        "version": "2.0"
      }
    },
    {
      "id": "document1#chunk2",
      "values": chunk2_vector,
      "metadata": {
        "document_id": "document1",
        "document_title": "Introduction to Vector Databases - Updated Edition",
        "chunk_number": 2,
        "chunk_text": "Updated second chunk with new content...",
        "document_url": "https://example.com/docs/document1",
        "created_at": "2024-02-15",
        "document_type": "tutorial",
        "version": "2.0"
      }
    }
    # Add more chunks as needed for the updated document
  ]
)

print("Successfully updated document1 with new chunks")
```

## Data freshness

Pinecone is [eventually consistent](/guides/index-data/check-data-freshness), so it's possible that a write (upsert, update, or delete) followed immediately by a read (query, list, or fetch) may not return the latest version of the data. If your use case requires retrieving data immediately, consider implementing a small delay or [retry logic](/guides/production/error-handling#implement-retry-logic) after writes.

## Design for multi-tenancy

Many applications have a concept of tenants—users, organizations, projects, or other groups that should only access their own data. How you model this access control significantly impacts query performance and cost.

### Use namespaces for tenant isolation

The most efficient way to implement multi-tenancy is to use [namespaces](/guides/index-data/indexing-overview#namespaces) to separate data by tenant. With this approach, each tenant has their own namespace, and queries only scan that tenant's data—resulting in better performance and lower costs.

For a complete implementation guide with examples across all SDKs, see [Implement multitenancy](/guides/index-data/implement-multitenancy).

<Accordion title="Why namespaces are more efficient">
  When you use namespaces for multi-tenancy:

  * **Lower query costs and faster performance**: Query cost is based on namespace size. If you have 100 tenants with 1 GB each, querying one tenant's namespace costs 1 RU and scans only 1 GB. With metadata filtering in a single namespace (100 GB total), the same query costs 100 RUs and scans all 100 GB, even though the filter narrows results.
  * **Natural isolation**: Reduces the risk of application bugs that could query the wrong tenant's data (for example, by passing an incorrect filter value).
</Accordion>

### Avoid filtering by high-cardinality IDs

A common anti-pattern is storing all data in a single namespace and using metadata filters to scope queries to specific users:

<CodeGroup>
  ```python Python theme={null}
  # Anti-pattern: Filtering by many user IDs
  query_vector = [0.1, 0.2, 0.3, ...]  # Your query vector
  results = index.query(
      vector=query_vector,
      top_k=10,
      filter={
          "allowed_user_ids": {"$in": ["user_1", "user_2", ..., "user_10000"]}
      }
  )
  ```

  ```javascript JavaScript theme={null}
  // Anti-pattern: Filtering by many user IDs
  const queryVector = [0.1, 0.2, 0.3, ...];  // Your query vector
  const results = await index.query({
    vector: queryVector,
    topK: 10,
    filter: {
      allowed_user_ids: { $in: ["user_1", "user_2", ..., "user_10000"] }
    }
  });
  ```

  ```java Java theme={null}
  // Anti-pattern: Filtering by many user IDs
  import com.google.protobuf.Struct;
  import com.google.protobuf.Value;
  import io.pinecone.clients.Index;
  import io.pinecone.clients.Pinecone;
  import io.pinecone.unsigned_indices_model.QueryResponseWithUnsignedIndices;
  import java.util.Arrays;
  import java.util.List;

  Pinecone pinecone = new Pinecone.Builder("YOUR_API_KEY").build();
  Index index = pinecone.getIndexConnection("your-index-name");
  List<Float> queryVector = Arrays.asList(0.1f, 0.2f, 0.3f, ...);  // Your query vector

  // Build filter with $in operator (up to 10,000 values)
  Struct.Builder filterBuilder = Struct.newBuilder();
  Value.Builder listValueBuilder = Value.newBuilder();
  listValueBuilder.getListValueBuilder()
      .addAllValues(Arrays.asList(
          Value.newBuilder().setStringValue("user_1").build(),
          Value.newBuilder().setStringValue("user_2").build()
          // ... up to 10,000 values
      ));
  filterBuilder.putFields("allowed_user_ids",
      Value.newBuilder()
          .setStructValue(Struct.newBuilder()
              .putFields("$in", listValueBuilder.build())
              .build())
          .build());
  Struct filter = filterBuilder.build();

  QueryResponseWithUnsignedIndices results = index.queryByVector(
      10,
      queryVector,
      null, // default namespace
      filter
  );
  ```

  ```go Go theme={null}
  // Anti-pattern: Filtering by many user IDs
  import (
      "context"
      "fmt"
      "log"
      "github.com/pinecone-io/go-pinecone/v5/pinecone"
      "google.golang.org/protobuf/types/known/structpb"
  )

  ctx := context.Background()

  clientParams := pinecone.NewClientParams{
      ApiKey: "YOUR_API_KEY",
  }
  pc, err := pinecone.NewClient(clientParams)
  if err != nil {
      log.Fatalf("Failed to create Client: %v", err)
  }

  idx, err := pc.DescribeIndex(ctx, "your-index-name")
  if err != nil {
      log.Fatalf("Failed to describe index: %v", err)
  }

  idxConnection, err := pc.Index(pinecone.NewIndexConnParams{
      Host: idx.Host,
  })
  if err != nil {
      log.Fatalf("Failed to create IndexConnection: %v", err)
  }

  queryVector := []float32{0.1, 0.2, 0.3, ...}  // Your query vector

  userIds := []interface{}{"user_1", "user_2", /* ... up to 10,000 values */}
  metadataMap := map[string]interface{}{
      "allowed_user_ids": map[string]interface{}{
          "$in": userIds,
      },
  }
  filter, err := structpb.NewStruct(metadataMap)
  if err != nil {
      log.Fatalf("Failed to create filter: %v", err)
  }

  queryReq := &pinecone.QueryByVectorValuesRequest{
      Vector:          queryVector,
      TopK:            10,
      MetadataFilter:  filter,
      IncludeMetadata: true,
  }
  results, err := idxConnection.QueryByVectorValues(ctx, queryReq)
  if err != nil {
      log.Fatalf("Failed to query: %v", err)
  }
  fmt.Printf("Found %d matches:\n", len(results.Matches))
  for _, match := range results.Matches {
      fmt.Printf("  ID: %s, Score: %.4f\n", match.Vector.Id, match.Score)
      if match.Vector.Metadata != nil {
          fmt.Printf("    Metadata: %v\n", match.Vector.Metadata)
      }
  }
  ```

  ```bash curl theme={null}
  # Anti-pattern: Filtering by many user IDs
  PINECONE_API_KEY="YOUR_API_KEY"
  INDEX_HOST="INDEX_HOST"

  curl -X POST "https://$INDEX_HOST/query" \
       -H "Api-Key: $PINECONE_API_KEY" \
       -H "Content-Type: application/json" \
       -H "X-Pinecone-Api-Version: 2025-10" \
       -d '{
             "vector": [0.1, 0.2, 0.3, ...],
             "topK": 10,
             "includeMetadata": true,
             "filter": {
               "allowed_user_ids": {
                 "$in": ["user_1", "user_2", ..., "user_10000"]
               }
             }
          }'
  ```
</CodeGroup>

This approach has several drawbacks:

* **Performance degradation**: Large `$in` filters increase network payload size and query latency.
* **Hard limits**: Each `$in` or `$nin` operator is limited to 10,000 values. Exceeding this limit will cause the request to fail. See [Metadata filter limits](/reference/api/database-limits#metadata-filter-limits).

### Use access control groups instead of individual IDs

If data must be shared across many tenants, design your access control using the smallest number of groups that describe a user's access:

<CodeGroup>
  ```python Python theme={null}
  # Better: Filter by organization or role instead of individual users
  query_vector = [0.1, 0.2, 0.3, ...]  # Your query vector
  results = index.query(
      vector=query_vector,
      top_k=10,
      filter={
          "$or": [
              {"organization_id": {"$eq": "org_A"}},
              {"project_id": {"$eq": "project_B"}}
          ]
      }
  )
  ```

  ```javascript JavaScript theme={null}
  // Better: Filter by organization or role instead of individual users
  const queryVector = [0.1, 0.2, 0.3, ...];  // Your query vector
  const results = await index.query({
    vector: queryVector,
    topK: 10,
    filter: {
      $or: [
        { organization_id: { $eq: "org_A" } },
        { project_id: { $eq: "project_B" } }
      ]
    }
  });
  ```

  ```java Java theme={null}
  // Better: Filter by organization or role instead of individual users
  import com.google.protobuf.Struct;
  import com.google.protobuf.Value;
  import io.pinecone.clients.Index;
  import io.pinecone.clients.Pinecone;
  import io.pinecone.unsigned_indices_model.QueryResponseWithUnsignedIndices;
  import java.util.Arrays;
  import java.util.List;

  Pinecone pinecone = new Pinecone.Builder("YOUR_API_KEY").build();
  Index index = pinecone.getIndexConnection("your-index-name");
  List<Float> queryVector = Arrays.asList(0.1f, 0.2f, 0.3f, ...);  // Your query vector

  // Build filter with $or operator
  Struct.Builder orgFilterBuilder = Struct.newBuilder();
  orgFilterBuilder.putFields("organization_id",
      Value.newBuilder()
          .setStructValue(Struct.newBuilder()
              .putFields("$eq", Value.newBuilder()
                  .setStringValue("org_A")
                  .build())
              .build())
          .build());

  Struct.Builder projectFilterBuilder = Struct.newBuilder();
  projectFilterBuilder.putFields("project_id",
      Value.newBuilder()
          .setStructValue(Struct.newBuilder()
              .putFields("$eq", Value.newBuilder()
                  .setStringValue("project_B")
                  .build())
              .build())
          .build());

  Struct.Builder orFilterBuilder = Struct.newBuilder();
  orFilterBuilder.putFields("$or",
      Value.newBuilder()
          .getListValueBuilder()
          .addValues(Value.newBuilder().setStructValue(orgFilterBuilder.build()).build())
          .addValues(Value.newBuilder().setStructValue(projectFilterBuilder.build()).build())
          .build());

  QueryResponseWithUnsignedIndices results = index.queryByVector(
      10,
      queryVector,
      null, // default namespace
      orFilterBuilder.build(),
      false, // includeValues
      true // includeMetadata
  );
  ```

  ```go Go theme={null}
  // Better: Filter by organization or role instead of individual users
  import (
      "context"
      "fmt"
      "log"
      "github.com/pinecone-io/go-pinecone/v5/pinecone"
      "google.golang.org/protobuf/types/known/structpb"
  )

  ctx := context.Background()

  clientParams := pinecone.NewClientParams{
      ApiKey: "YOUR_API_KEY",
  }
  pc, err := pinecone.NewClient(clientParams)
  if err != nil {
      log.Fatalf("Failed to create Client: %v", err)
  }

  idx, err := pc.DescribeIndex(ctx, "your-index-name")
  if err != nil {
      log.Fatalf("Failed to describe index: %v", err)
  }

  idxConnection, err := pc.Index(pinecone.NewIndexConnParams{
      Host: idx.Host,
  })
  if err != nil {
      log.Fatalf("Failed to create IndexConnection: %v", err)
  }

  queryVector := []float32{0.1, 0.2, 0.3, ...}  // Your query vector

  metadataMap := map[string]interface{}{
      "$or": []interface{}{
          map[string]interface{}{
              "organization_id": map[string]interface{}{
                  "$eq": "org_A",
              },
          },
          map[string]interface{}{
              "project_id": map[string]interface{}{
                  "$eq": "project_B",
              },
          },
      },
  }
  filter, err := structpb.NewStruct(metadataMap)
  if err != nil {
      log.Fatalf("Failed to create filter: %v", err)
  }

  queryReq := &pinecone.QueryByVectorValuesRequest{
      Vector:          queryVector,
      TopK:            10,
      MetadataFilter:  filter,
      IncludeMetadata: true,
  }
  results, err := idxConnection.QueryByVectorValues(ctx, queryReq)
  if err != nil {
      log.Fatalf("Failed to query: %v", err)
  }
  fmt.Printf("Found %d matches:\n", len(results.Matches))
  for _, match := range results.Matches {
      fmt.Printf("  ID: %s, Score: %.4f\n", match.Vector.Id, match.Score)
      if match.Vector.Metadata != nil {
          fmt.Printf("    Metadata: %v\n", match.Vector.Metadata)
      }
  }
  ```

  ```bash curl theme={null}
  # Better: Filter by organization or role instead of individual users
  PINECONE_API_KEY="YOUR_API_KEY"
  INDEX_HOST="INDEX_HOST"

  curl -X POST "https://$INDEX_HOST/query" \
       -H "Api-Key: $PINECONE_API_KEY" \
       -H "Content-Type: application/json" \
       -H "X-Pinecone-Api-Version: 2025-10" \
       -d '{
             "vector": [0.1, 0.2, 0.3, ...],
             "topK": 10,
             "includeMetadata": true,
             "filter": {
               "$or": [
                 {"organization_id": {"$eq": "org_A"}},
                 {"project_id": {"$eq": "project_B"}}
               ]
             }
          }'
  ```
</CodeGroup>

Instead of passing thousands of user IDs, this filter uses only 2 group identifiers to achieve the same access control.

### Multitenancy patterns

The following table provides general guidelines for choosing a multitenancy approach. Evaluate your specific use case, access patterns, and requirements to determine the best fit for your application.

| Data pattern                              | Recommended approach                                                  | Query cost                             | Performance |
| :---------------------------------------- | :-------------------------------------------------------------------- | :------------------------------------- | :---------- |
| Each tenant's data is completely separate | One index, one namespace per tenant                                   | Lowest (scans only tenant namespace)   | Fastest     |
| Large tenants with many sub-groups        | One index per large tenant, namespaces for sub-groups                 | Low (scans only sub-group namespace)   | Fast        |
| Data shared across tenants                | One index, shared namespace, filter by group IDs (org, project, role) | Higher (scans entire shared namespace) | Slower      |

<Warning>
  Avoid filtering by large lists of individual user IDs (for example, `{"user_id": {"$in": ["user_1", "user_2", ..., "user_10000"]}}`). This approach has the following drawbacks:

  * Hard limits: Each `$in` or `$nin` operator is limited to 10,000 values. Exceeding this limit will cause requests to fail.
  * Performance: Large filters increase query latency.
  * Higher costs: You pay for scanning the entire shared namespace, even though the filter narrows results.

  Instead, consider these alternatives:

  * Use one namespace per tenant (see row 1 in the table above).
  * Filter by broader groups like organization, project, or role rather than individual user IDs (see row 3 in the table above).
  * Retrieve a larger top K without filtering (for example, top 1000), then filter the results client-side.
</Warning>

For a complete step-by-step implementation guide, see [Implement multitenancy](/guides/index-data/implement-multitenancy).


# Dedicated Read Nodes
Source: https://docs.pinecone.io/guides/index-data/dedicated-read-nodes

Dedicated read nodes use provisioned hardware for read operations, providing predictable, low-latency performance at high query volumes.

## Overview

Pinecone indexes built on dedicated read nodes use provisioned read hardware to provide predictable, consistent performance at sustained, high query volumes. They're designed for large-scale vector workloads such as semantic search, recommendation engines, and mission-critical services.

Dedicated read nodes differ from on-demand indexes in how they handle read operations. While on-demand indexes use shared, multi-tenant capacity for reads, dedicated read nodes provision exclusive hardware for reads—memory, local SSDs, and compute. Both index types use Pinecone's serverless infrastructure for writes and storage.

When you create a dedicated read nodes index, Pinecone provisions resources based on your choice of [node type](#node-types), number of [shards](#shards), and number of [replicas](#replicas). These resources include local SSDs and memory that cache all your index data, and provide dedicated query executors to handle read operations (query, fetch, list). This architecture eliminates cold starts and ensures consistent low-latency performance, even under heavy load.

Dedicated read nodes support dense, sparse, hybrid, and [full-text search](/guides/search/full-text-search) indexes, giving you flexibility in your search and retrieval strategy. Because storage (shards) and compute (replicas) scale independently, you can optimize for your specific workload characteristics.

<Frame>
  <img />

  <img />
</Frame>

## On-demand vs dedicated

On-demand indexes and dedicated read nodes are both built on Pinecone's serverless infrastructure. They use the same write path, storage layer, and data operations API.

However, every dedicated read nodes index has isolated hardware for read operations (query, fetch, list), allowing these operations to run on dedicated query executors. This affects performance, cost, and how you scale:

| Feature                 | On-demand                                                                                                                                      | Dedicated read nodes                                                                                                                                               |
| :---------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Read infrastructure** | Multi-tenant compute resources shared across customers                                                                                         | Isolated, provisioned query executors dedicated to your index                                                                                                      |
| **Read costs**          | Pay per [read unit](/guides/manage-cost/understanding-cost#serverless-indexes) (1 RU per 1 GB of namespace size per query, minimum 0.25 RU)    | Fixed hourly rate for read capacity based on node type, shards, and replicas                                                                                       |
| **Other costs**         | [Storage](/guides/manage-cost/understanding-cost#storage) and [write](/guides/manage-cost/understanding-cost#write-units) costs based on usage | [Storage](/guides/manage-cost/understanding-cost#storage) and [write](/guides/manage-cost/understanding-cost#write-units) costs based on usage (same as on-demand) |
| **Caching**             | Best-effort; frequently accessed data is cached, but cold queries fetch from object storage                                                    | Guaranteed; all index data always warm in memory and on local SSDs                                                                                                 |
| **Read rate limits**    | [2,000 RUs/second per index (adjustable)](/reference/api/database-limits#rate-limits)                                                          | No read rate limits (only bounded by CPU capacity)                                                                                                                 |
| **Scaling**             | Automatic; Pinecone handles capacity                                                                                                           | Manual; add [shards](#shards) for storage, add [replicas](#replicas) for throughput                                                                                |
| **Query-time tuning**   | Parameters accepted but have no effect                                                                                                         | Optional [`scan_factor` and `max_candidates`](#query-time-search-parameters) to trade recall for lower latency and higher throughput                               |
| **Best for**            | Variable workloads, multi-tenant applications with many namespaces, low to moderate query rates                                                | Sustained high query rates, large single-namespace workloads, predictable performance and cost                                                                     |

## When to use dedicated read nodes

Dedicated read nodes are ideal for workloads with millions to billions of records and predictable query rates. They provide performance and cost benefits compared to on-demand for high-throughput workloads, and may be required when your workload exceeds on-demand rate limits.

There's no universal formula for choosing between on-demand and dedicated read nodes—performance and cost vary by workload (vector dimensionality, metadata filtering, and query patterns). Consider the following factors when making your decision:

<AccordionGroup>
  <Accordion title="Predictable, consistent performance and cost">
    With dedicated read nodes, you allocate dedicated read hardware for your index, and your data is cached in memory and on local SSDs. This provides:

    * Consistent low latency under heavy load.
    * No cold starts (fetching data from object storage).
    * Performance isolation from other workloads.
    * Linear scaling by adding replicas.
    * Predictable costs based on fixed hourly rates for provisioned hardware.

    If predictable performance and cost are critical for your application, dedicated read nodes may be a better fit than on-demand.
  </Accordion>

  <Accordion title="High throughput without rate limits or throttling">
    On-demand indexes are subject to [read unit rate limits](/reference/api/database-limits#rate-limits) (default: 2,000 RUs/second per index).

    A high query volume on a large index can exceed these limits. For example, a 15 GB namespace at 150 QPS requires approximately 2,250 RUs/second (`15 RUs per query × 150 QPS`), which exceeds the default rate limit.

    Dedicated read nodes have no read rate limits and provide dedicated capacity for predictable QPS without throttling (bounded only by CPU capacity), making them better suited for high-throughput workloads.
  </Accordion>

  <Accordion title="Recommendation engines and real-time use cases">
    Recommendation engines for use cases such as e-commerce and media require very high throughput and low latency to maintain positive user experiences. Dedicated read nodes are purpose-built for these use cases, providing:

    * Consistent performance for thousands of queries per second
    * Low latency for real-time recommendations
    * Scalability to billion-vector datasets
    * No performance degradation during traffic spikes

    Similar requirements apply to other real-time use cases like semantic search at scale, personalization engines, and mission-critical services with strict performance SLOs.
  </Accordion>

  <a />

  <Accordion title="Single namespace workload (multi-namespace coming soon)">
    Dedicated read nodes indexes support only a single namespace. If your application requires multiple namespaces, on-demand is a better fit.

    <Note>
      Multi-namespace support is coming soon. For early access, [contact us](https://www.pinecone.io/contact/).
    </Note>
  </Accordion>

  <Accordion title="When NOT to use dedicated read nodes">
    On-demand indexes are better suited for workloads with unpredictable or highly variable traffic patterns. For example:

    * RAG systems with variable query volumes
    * Agentic applications with sporadic usage
    * Prototypes and development environments with intermittent activity
    * Scheduled jobs with infrequent, batch-style queries

    Additionally, on-demand is better for indexes with many namespaces, even if you have high query volumes. Dedicated read nodes currently only support single-namespace indexes, so multi-tenant applications requiring namespace-based isolation should use on-demand until multi-namespace support is available.

    For these scenarios, on-demand's elasticity and usage-based pricing provide better cost efficiency than provisioning dedicated capacity.

    <Note>
      Dedicated read nodes **can** handle predictable traffic spikes efficiently if you scale replicas proactively via the API. For example, you can provision extra replicas before a scheduled email campaign and scale back down afterward. Auto-scaling will be available in a future release.
    </Note>
  </Accordion>

  <Accordion title="Cost considerations">
    On-demand and dedicated read nodes have different cost structures. The key difference is read costs: on-demand uses usage-based pricing, while dedicated read nodes use a fixed hourly rate based on provisioned hardware. Write and storage costs are usage-based for both modes.

    Dedicated read nodes become cost-effective when you have predictable, sustained query volumes that make full use of your provisioned capacity. With unpredictable or low query volumes, you pay hourly rates even when your machines sit idle, making on-demand's usage-based pricing more economical.

    For detailed cost information, comparison tables, and estimation tools, see the [Cost](#cost) section of this guide.
  </Accordion>

  <Accordion title="Test results for your workload">
    Performance depends on your specific workload — index size, vector dimensionality, metadata filtering, query patterns, throughput requirements, and latency requirements. Testing is the only way to know for sure whether dedicated read nodes are right for your scenario.

    For a step-by-step guide to testing, see [Test your workload](#test-your-workload).
  </Accordion>
</AccordionGroup>

If you need guidance choosing a capacity mode (on-demand or dedicated read nodes) or sizing your index configuration, [contact us](https://www.pinecone.io/contact/).

## Key concepts

Before creating a dedicated read nodes index, understand the configuration options that determine capacity and performance.

### Node types

A node is the basic unit of compute and cache storage capacity for a dedicated read nodes index. Each shard runs on one node, so the node type you choose determines the performance characteristics and cost of your index. The total number of nodes in your index is calculated as `shards × replicas`. For example, an index with two shards and two replicas uses four nodes.

There are two node types: `b1` and `t1`. Both are suitable for large-scale and demanding workloads, but they differ in processing power and memory capacity, and they cache different data.

|                      | **b1 (Balanced)**                                                               | **t1 (Performance)**                                                                                            |
| -------------------- | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| **Memory caching**   | Vector index stored in memory                                                   | Vector index + vector projections cached in memory                                                              |
| **Use case**         | Predictable performance for sustained query rates with balanced cost efficiency | Highest performance for the most demanding workloads with extreme query volumes and strict latency requirements |
| **Storage**          | 250 GB per shard                                                                | 250 GB per shard                                                                                                |
| **Compute & memory** | Base-level compute and memory resources                                         | \~4x more compute and memory than `b1`                                                                          |
| **Cost**             | Lower-cost option                                                               | \~3x the cost of `b1`                                                                                           |

Consider using `t1` nodes if your performance requirements are not met by `b1` nodes, or if `t1` nodes are more cost-effective than `b1` nodes for your workload.

<Note>
  When choosing a node type, remember that:

  * Both types of nodes provide 250 GB of storage per shard. The difference is in compute and memory, which affects query performance.
  * Because `t1` nodes cache more data in memory than `b1` nodes, an index may require more shards on `t1` than on `b1` (for the same data).
  * You can [change node types](#change-node-types) after creating your index.
</Note>

### Shards

Shards determine the storage capacity of an index. Each shard provides 250 GB of storage, and data is split across all the shards in an index. To respond to a query, the index gathers data from all shards as needed. To determine how many shards you need, [calculate your index size](#calculate-the-size-of-your-index) and then [calculate the number of shards](#number-of-shards).

<Warning>
  It's your responsibility to allocate enough shards to accommodate the size of your index. If your index exceeds the capacity of its shards, write operations (upsert, update, delete) are blocked, but read operations continue to work normally.
</Warning>

### Replicas

Replicas multiply the compute resources and data of an index, allowing for higher query throughput and availability. Each replica is a complete copy of your index data and has its own dedicated compute resources.

* Throughput scales approximately linearly with replicas. For example, if one replica handles 50 QPS at your target latency, two replicas should handle approximately 100 QPS.
* You can scale replicas up or down with no downtime using the API. See [Add or remove replicas](#add-or-remove-replicas).
* Minimum: 0 replicas ([pauses the index](#pause-an-index)).
* For high availability, use at least two replicas. The recommended approach is to allocate `n+1` replicas where `n` is your minimum for throughput. Pinecone distributes replicas across availability zones (up to three per region), so if one zone fails, remaining replicas continue serving queries.

To determine how many replicas you need, [test your workload](#test-your-workload) and then [calculate the number of replicas](#number-of-replicas).

<Note>
  Actual performance varies based on workload characteristics (query complexity, vector dimensions, metadata characteristics), [metadata filter](/guides/search/filter-by-metadata) selectivity, and [node type](#node-types) (`b1` vs `t1`). Always test with your specific workload.
</Note>

### Index fullness

Index fullness measures how much of your index's allocated capacity is being used. To ensure predictable performance, dedicated read nodes cache your data in memory and on local SSD.

* You can use Pinecone's API to [check index fullness](#monitor-index-fullness). There are three metrics to monitor: `memoryFullness`, `storageFullness`, and `indexFullness`.
  <Note>
    `indexFullness` is the maximum of `memoryFullness` and `storageFullness`.
  </Note>
* Usually, storage fills up first. However, memory can be the limiting factor when you have `b1` nodes with many low-dimension vectors, or when you have `t1` nodes with high-dimension vectors and lots of metadata.
* Monitor fullness regularly and [add shards](#add-or-remove-shards) before your index reaches capacity. When `indexFullness` reaches 1.0 (100%), write operations (upsert, update, delete) are blocked, but read operations continue to work normally.

<Note>
  Add shards when [index fullness](#index-fullness) reaches 70-80%, especially if you expect continued growth. Adding shards reduces storage fullness (index data is spread across shards, so each stores less) and memory fullness (with less data per shard, there's less to cache in memory), helping you avoid write failures.
</Note>

## Query-time search parameters

Dedicated read nodes support two optional query-time parameters — `scan_factor` and `max_candidates` — that let you trade off recall (search quality) for lower latency and higher throughput. By default, queries use internal heuristics that favor recall. If your application is latency-sensitive or needs higher QPS, you can tune these parameters to reduce the work done per query — or increase them for higher recall.

These parameters only take effect on dedicated read nodes indexes with dense vectors. On on-demand indexes, the parameters are accepted but have no effect. On indexes that store only sparse vectors, specifying either parameter returns an error. Using these parameters requires API version `2025-10` or later.

### How scan\_factor and max\_candidates work

Dense vector search on dedicated read nodes uses a two-stage pipeline:

1. **Scanning** — controlled by `scan_factor`. For IVF-based indexes, the system scans a fraction of partitions determined by `scan_factor / sqrt(num_partitions)`. A lower `scan_factor` scans fewer partitions, producing fewer candidates faster. This parameter only affects IVF-based slabs; for other index architectures (e.g., smaller indexes using flat search), `scan_factor` has no effect.
2. **Reranking** — controlled by `max_candidates`. The top candidates from the scanning stage are reranked by computing exact distances. More reranking improves recall but increases latency. This parameter applies to all index architectures.

The two parameters affect different stages and their effects are additive — you can set both to optimize each stage independently.

| Parameter            | Type    | Range                                | Default                                                         | Description                                                                                                                                |
| :------------------- | :------ | :----------------------------------- | :-------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------- |
| **`scan_factor`**    | Float   | 0.5–4.0                              | 4.0                                                             | Controls how much of the IVF index is scanned to find vector candidates. Lower values scan fewer partitions and return results faster.     |
| **`max_candidates`** | Integer | Your query's `top_k` value – 100,000 | 2500 (see [default behavior](#default-max_candidates-behavior)) | Maximum number of candidate vectors to rerank with exact distance computation. Higher values improve recall; lower values improve latency. |

You can set one or both per query. Omitting both preserves the current default behavior, so existing applications are unaffected.

#### Default `max_candidates` behavior

When `max_candidates` is not set, the system calculates an effective value using the following formula:

* If `top_k` \<= 1000: `min(top_k * 10, 1000)`
* If `top_k` > 1000: `top_k`
* Then, a floor of 2500 is applied (the effective value is at least 2500)

For most queries (where `top_k` \<= 2500), the effective default is **2500**. This is not the maximum possible value — you can raise `max_candidates` (up to 100,000) to increase recall, or lower it (down to your query's `top_k`) to reduce latency.

When you explicitly set `max_candidates`, the value you provide is used directly, bypassing the formula and the floor.

### Impact on recall and performance

Lower `scan_factor` or `max_candidates` values reduce the work done per query, which improves latency and throughput but may reduce recall. The tables below summarize benchmarked behavior on a 2.68M-vector index (1536 dimensions, cosine similarity). Actual results are dataset-dependent.

#### `scan_factor` benchmarks

Starting from the default (4.0), lowering `scan_factor` reduces the fraction of IVF partitions scanned:

| scan\_factor  | Approximate recall (p50) | Relative throughput |
| :------------ | :----------------------- | :------------------ |
| 4.0 (default) | \~96%                    | 1x (baseline)       |
| 2.0           | \~94%                    | \~1.5x              |
| 1.0           | \~91%                    | \~2x                |
| 0.5           | \~84%                    | \~4x                |

Testing shows that lower `scan_factor` values can reduce p50 and p99 latency by 30–50% or more.

#### Tuning `max_candidates`

Higher `max_candidates` improves recall by reranking more candidates but increases latency and reduces throughput; lower values favor speed. For guidance on choosing values, see [Tuning guidance](#tuning-guidance). We recommend benchmarking on your own dataset and workload to find the right balance—use the [Test your workload](#test-your-workload) process to validate latency and recall.

### Tuning guidance

Start with the defaults and adjust based on your workload requirements:

* **To optimize for throughput/latency:** Lower `scan_factor` first (from the default of 4.0). This has the most impact on IVF-based indexes. If you need further improvement, lower `max_candidates` below the default of 2500 (down to your query's `top_k` value).
* **To optimize for recall:** Raise `max_candidates` above the default of 2500 (up to 100,000). This reranks more candidate vectors at the cost of higher latency.

**Trade-offs to consider:**

* **Adjust one parameter at a time.** `scan_factor` controls the scanning stage (IVF only) and `max_candidates` controls the reranking stage (all index types). Tuning them independently makes it easier to isolate the effect.
* **Safe defaults:** Omitting both parameters preserves existing behavior. There is no risk to existing queries.
* **Cost reduction:** By achieving higher throughput per node, you may be able to serve the same query rate with fewer replicas.

### Behavior by vector type

| Index / query type                               | Behavior                                                                                                                                                                                                      |
| :----------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Dense vectors, dense query**                   | `scan_factor` and `max_candidates` apply normally.                                                                                                                                                            |
| **Dense vectors, hybrid query (dense + sparse)** | Both parameters apply to the dense component only; the sparse component is unaffected.                                                                                                                        |
| **Sparse vectors only**                          | Specifying `scan_factor` or `max_candidates` returns an error.                                                                                                                                                |
| **On-demand index**                              | Both parameters are accepted but have no effect on search behavior. You can use the same query code against on-demand (e.g., for development) and dedicated read nodes (for production) without modification. |

### API and SDK examples

Both parameters are optional fields on the `POST /query` request.

<CodeGroup>
  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  INDEX_HOST="YOUR_INDEX_HOST"

  curl -X POST "https://$INDEX_HOST/query" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "Content-Type: application/json" \
    -H "X-Pinecone-Api-Version: 2025-10" \
    -d '{
      "namespace": "example-namespace",
      "topK": 10,
      "vector": [0.1, 0.2, 0.3],
      "scanFactor": 1.0,
      "maxCandidates": 1000
    }'
  ```

  ```python Python theme={null}
  # Both parameters — balanced recall and latency
  index.query(
      namespace="example-namespace",
      vector=[0.1, 0.2, 0.3],
      top_k=10,
      scan_factor=1.0,
      max_candidates=1000
  )

  # scan_factor only — faster queries, lower recall
  index.query(
      namespace="example-namespace",
      vector=[0.1, 0.2, 0.3],
      top_k=10,
      scan_factor=0.5
  )

  # Omit both for maximum recall (default behavior)
  index.query(
      namespace="example-namespace",
      vector=[0.1, 0.2, 0.3],
      top_k=10
  )
  ```

  ```typescript TypeScript theme={null}
  // Both parameters — balanced recall and latency
  await index.query({
    namespace: "example-namespace",
    vector: [0.1, 0.2, 0.3],
    topK: 10,
    scanFactor: 1.0,
    maxCandidates: 1000
  });

  // scan_factor only — faster queries, lower recall
  await index.query({
    namespace: "example-namespace",
    vector: [0.1, 0.2, 0.3],
    topK: 10,
    scanFactor: 0.5
  });
  ```
</CodeGroup>

**Validation errors:**

| Condition                                                                               | Error message                                                                                         |
| :-------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------- |
| API version earlier than `2025-10`                                                      | `scan_factor and max_candidates parameters require API version 2025-10 or later`                      |
| `scan_factor` outside 0.5–4.0                                                           | `scan_factor must be between 0.5 and 4.0, got &lcub;value&rcub;`                                      |
| `max_candidates` below your query's `top_k` or above 100,000                            | `max_candidates must be between &lcub;top_k&rcub; (top_k) and &lcub;max&rcub;, got &lcub;value&rcub;` |
| Used on an index that stores only sparse vectors (API error text says "sparse indexes") | `scan_factor and max_candidates parameters are not supported for sparse indexes`                      |

<Note>
  `scan_factor` and `max_candidates` do not affect billing. Read costs for dedicated read nodes are based on provisioned capacity (node type, shards, and replicas), not per-query effort. By tuning these parameters to achieve higher throughput, you may be able to serve the same query rate with fewer provisioned replicas, reducing your overall cost.
</Note>

## Test your workload

To choose between on-demand and dedicated read nodes, or to optimize your dedicated read nodes configuration, test with your actual workload. Performance varies based on factors such as the size of your index,vector dimensionality, metadata characteristics, and query patterns.

<Steps>
  <Step title="Calculate the size of your index">
    [Calculate the size of your index](#calculate-the-size-of-your-index) to determine how many shards it requires.
  </Step>

  <Step title="Create and populate a test index">
    [Create a dedicated read nodes index](#create-a-dedicated-read-nodes-index) with representative data for your workload. You'll use this index for testing.

    <Tip>
      If you don't restore your test index from a backup, you can [upsert](/guides/index-data/upsert-data) or [import](/guides/index-data/import-data) your data.
    </Tip>
  </Step>

  <Step title="Migrate your test index to dedicated read nodes (if necessary)">
    If your test index is on-demand, [migrate it to dedicated read nodes](#migrate-to-dedicated-read-nodes). To start, use a single `b1` replica.

    <Warning>
      Don't migrate your production index yet. At this point, you're just testing your workload.
    </Warning>
  </Step>

  <Step title="Run a load test">
    Run realistic query patterns against your test index, gradually increasing QPS. For example, start at 10 QPS for about 30 minutes, then increase by 10 QPS increments while monitoring latency. Identify the QPS where latency exceeds your target threshold.
  </Step>

  <Step title="Calculate replicas">
    Throughput scales approximately linearly with replicas. For example, if one replica handles 50 QPS at your target latency, two replicas should handle approximately 100 QPS. However, performance can vary based on metadata filter selectivity.

    To calculate the number of replicas required for your target QPS, use this formula, rounding up:

    ```
    Minimum replicas = (Required QPS) / (QPS per replica)
    ```

    For more information, see [Number of replicas](#number-of-replicas).
  </Step>

  <Step title="Adjust and re-test">
    To meet your performance and cost goals, adjust your configuration as needed and re-test:

    * [Add or remove shards](#add-or-remove-shards) for storage capacity
    * [Add or remove replicas](#add-or-remove-replicas) for throughput
    * [Change node types](#change-node-types) for different performance characteristics

    Continue iterating until you meet your requirements with room for growth.
  </Step>
</Steps>

## Calculate the size of your index

To determine how many [shards](#shards) your index requires, calculate your index size and then use the formula in the [section](#number-of-shards) below.

### Index size

A record can include a dense vector, a sparse vector, or both. Use the formula that matches your data to calculate total size:

<div>
  <Tabs>
    <Tab title="Index of dense vectors">
      An [index of dense vectors](/guides/index-data/indexing-overview#indexes-with-dense-vectors) contains records with one dense vector each.

      <Note>
        Records can also contain sparse vectors (when the index metric is set to `dotproduct`), which can be useful for [hybrid search](/guides/search/hybrid-search#use-a-single-index-for-dense-and-sparse-vectors). To learn how to calculate size in that case, see [Index with both dense and sparse vectors](#index-with-both-dense-and-sparse-vectors).
      </Note>

      **Calculate size (assuming no sparse vectors)**

      ```
      Index size = Number of records × (
                     ID size + 
                     Metadata size +
                     Dense vector dimensions × 4 bytes
                   )
      ```

      Where:

      * `ID size` and `Metadata size` are measured in bytes, averaged across all records.
      * Each `Dense vector dimension` uses 4 bytes.

      **Example calculations**

      These examples assume 8-byte IDs:

      | Records    | Dense vector dimensions | Avg metadata size | Index size |
      | :--------- | :---------------------- | :---------------- | :--------- |
      | 500,000    | 768                     | 500 bytes         | 1.79 GB    |
      | 1,000,000  | 1536                    | 1,000 bytes       | 7.15 GB    |
      | 5,000,000  | 1024                    | 15,000 bytes      | 95.5 GB    |
      | 10,000,000 | 1536                    | 1,000 bytes       | 71.5 GB    |

      <Note>
        Example: 500,000 records × (8-byte ID + (768 dense vector dimensions × 4 bytes) + 500 bytes of metadata) = 1.79 GB
      </Note>
    </Tab>

    <Tab title="Index of sparse vectors">
      An [index of sparse vectors](/guides/index-data/indexing-overview#indexes-with-sparse-vectors) contains records with one sparse vector each.

      **Calculate size**

      ```
      Index size = Number of records × (
                     ID size + 
                     Metadata size +
                     Number of non-zero sparse values × 8 bytes
                   )
      ```

      Where:

      * `ID size` and `Metadata size` are measured in bytes, averaged across all records.
      * `Number of non-zero sparse values`: Average number across all records. To find the count for a single record, check the length of the sparse vector's `indices` or `values` array. Each non-zero value uses 8 bytes.

      **Example calculations**

      These examples assume 8-byte IDs:

      | Records    | Avg number of non-zero sparse values | Avg metadata size | Index size |
      | :--------- | :----------------------------------- | :---------------- | :--------- |
      | 500,000    | 10                                   | 500 bytes         | 0.29 GB    |
      | 1,000,000  | 50                                   | 1,000 bytes       | 1.41 GB    |
      | 5,000,000  | 100                                  | 15,000 bytes      | 79.0 GB    |
      | 10,000,000 | 50                                   | 1,000 bytes       | 14.1 GB    |

      <Note>
        Example: 500,000 records × (8-byte ID + (10 non-zero sparse values × 8 bytes) + 500 bytes of metadata) = 0.29 GB
      </Note>
    </Tab>

    <Tab title="Index with both dense and sparse vectors">
      An [index with both dense and sparse vectors](/guides/search/hybrid-search#use-a-single-index-for-dense-and-sparse-vectors) contains records that each have one dense vector and an optional sparse vector.

      **Calculate size**

      ```
      Index size = Number of records × (
                     ID size + 
                     Metadata size +
                     Dense vector dimensions × 4 bytes + 
                     Number of non-zero sparse values × 8 bytes
                   )
      ```

      Where:

      * `ID size` and `Metadata size` are measured in bytes, averaged across all records.
      * Each `Dense vector dimension` uses 4 bytes.
      * `Number of non-zero sparse values`: Average number across all records, including those without sparse vectors. To find the count for a single record, check the length of the sparse vector's `indices` or `values` array. Each non-zero value uses 8 bytes.

      **Example calculations**

      These examples assume 8-byte IDs:

      | Records    | Dense vector dimensions | Avg number of non-zero sparse values | Avg metadata size | Index size |
      | :--------- | :---------------------- | :----------------------------------- | :---------------- | :--------- |
      | 500,000    | 768                     | 10                                   | 500 bytes         | 1.83 GB    |
      | 1,000,000  | 1536                    | 50                                   | 1,000 bytes       | 7.54 GB    |
      | 5,000,000  | 1024                    | 100                                  | 15,000 bytes      | 99.5 GB    |
      | 10,000,000 | 1536                    | 50                                   | 1,000 bytes       | 75.4 GB    |

      <Note>
        Example: 500,000 records × (8-byte ID + (768 dense vector dimensions × 4 bytes) + (10 non-zero sparse values × 8 bytes) + 500 bytes of metadata) = 1.83 GB
      </Note>
    </Tab>
  </Tabs>
</div>

### Number of shards

To calculate the number of shards your index requires, divide the size of your index by 250 GB and round up:

```
Minimum shards = (Index size) / (250 GB per shard)
```

To maintain optimal performance, provision additional shards to keep your index at 70-80% capacity. For example, a 500 GB index should have three shards (750 GB capacity = 67% full), not two shards (500 GB capacity = 100% full).

**Example shard calculations**

| Index size   | Minimum shards       | Recommended shards   |
| :----------- | :------------------- | :------------------- |
| **\~71 GB**  | 1 (250 GB; 28% full) | 1 (250 GB; 28% full) |
| **\~300 GB** | 2 (500 GB; 60% full) | 2 (500 GB; 60% full) |
| **\~400 GB** | 2 (500 GB; 80% full) | 3 (750 GB; 53% full) |

**Other considerations**

* Every index must have at least one shard. However, you can [pause an index](#pause-an-index) by reducing its replicas to 0.
* After you've created your index, [monitor its fullness](#monitor-index-fullness). When your index approaches capacity, you can [add shards](#add-or-remove-shards).

<Note>
  Add shards when [index fullness](#index-fullness) reaches 70-80%, especially if you expect continued growth. Adding shards reduces storage fullness (index data is spread across shards, so each stores less) and memory fullness (with less data per shard, there's less to cache in memory), helping you avoid write failures.
</Note>

### Number of replicas

To calculate the number of replicas your index requires, first [test your workload](#test-your-workload) to find the QPS a single replica can handle at your target latency. Then, use this formula, and round up:

```
Minimum replicas = (Required QPS) / (QPS per replica)
```

For example, if one replica handles 50 QPS at your target latency and you need 150 QPS, you need three replicas.

**Other considerations**

* Throughput scales approximately linearly with replicas, but performance can vary based on metadata filter selectivity.
* For high availability, allocate `n+1` replicas where `n` is your minimum for throughput. Pinecone distributes replicas across availability zones.

## Create a dedicated read nodes index

You can create a dedicated read nodes index from scratch or from a backup of an existing index.

### From scratch

To create a new dedicated read nodes index from scratch, call [Create an index](/reference/api/2025-10/control-plane/create_index). In the request body, in the `spec.serverless.read_capacity` object, set the following fields:

| Field                           | Value                                            | Notes                                                  |
| :------------------------------ | :----------------------------------------------- | :----------------------------------------------------- |
| **`mode`**                      | `Dedicated`                                      |                                                        |
| **`dedicated.node_type`**       | `b1` or `t1`                                     | See [node types](#node-types)                          |
| **`dedicated.scaling`**         | `Manual`                                         | Currently the only option                              |
| **`dedicated.manual.shards`**   | Number of [shards](#number-of-shards) needed     | Minimum 1 shard; each shard provides 250 GB of storage |
| **`dedicated.manual.replicas`** | Number of [replicas](#number-of-replicas) needed | Minimum 0 (this [pauses](#pause-an-index) the index)   |

<Note>
  To learn how to determine the number of shards and replicas your index requires, see [Calculate the size of your index](#calculate-the-size-of-your-index).
</Note>

**Example**

<CodeGroup>
  ```bash curl expandable theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"

  curl -X POST "https://api.pinecone.io/indexes" \
       -H "Accept: application/json" \
       -H "Content-Type: application/json" \
       -H "Api-Key: $PINECONE_API_KEY" \
       -H "X-Pinecone-Api-Version: 2025-10" \
       -d '{
             "name": "example-dedicated-index",
             "dimension": 1024,
             "metric": "cosine",
             "deletion_protection": "enabled",
             "tags": {
               "environment": "production"
             },
             "vector_type": "dense",
             "spec": {
               "serverless": {
                 "cloud": "aws",
                 "region": "us-east-1",
                 "read_capacity": {
                   "mode": "Dedicated",
                   "dedicated": {
                     "node_type": "b1",
                     "scaling": "Manual",
                     "manual": {
                       "shards": 2,
                       "replicas": 1
                     }
                   }
                 }
               }
             }
           }'
  ```
</CodeGroup>

Example response:

<CodeGroup>
  ```jsonc curl expandable theme={null}
  {
    "name": "example-dedicated-index",
    "vector_type": "dense",
    "metric": "cosine",
    "dimension": 1024,
    "status": {
      "ready": false,
      "state": "Initializing"
    },
    "host": "example-dedicated-index-1c6ab6aa.svc.aped-4627-b74a.pinecone.io",
    "spec": {
      "serverless": {
        "region": "us-east-1",
        "cloud": "aws",
        "read_capacity": {
          "mode": "Dedicated",
          "dedicated": {
            "node_type": "b1",
            "scaling": "Manual",
            "manual": {
              "shards": 2, // <---- desired state
              "replicas": 1
            }
          },
          "status": {
            "state": "Migrating",
            "current_shards": null, // <---- current state
            "current_replicas": null
          }
        }
      }
    },
    "deletion_protection": "enabled",
    "tags": {
      "environment": "production"
    }
  }
  ```
</CodeGroup>

The response includes two status fields:

| Field                                            | Description                                                                |
| :----------------------------------------------- | :------------------------------------------------------------------------- |
| **`status.state`**                               | Overall index status (for example, `Initializing`, `Ready`, `Terminating`) |
| **`spec.serverless.read_capacity.status.state`** | Read capacity status (`Migrating`, `Scaling`, `Ready`, `Error`)            |

<Note>
  When creating a dedicated read nodes index, `status.state` transitions to `Ready` as soon as the index is ready for reads and writes.

  However, `spec.serverless.read_capacity.status.state` remains `Migrating` until the index scales to its full read capacity, at which point it transitions to `Ready`.
</Note>

After creating the index, [upsert](/guides/index-data/upsert-data) or [import](/guides/index-data/import-data) your data.

<Tip>
  To upsert and search with text instead of vectors, you can configure your index to use a [hosted embedding model](/guides/index-data/create-an-index#embedding-models). Call [Configure an index](/reference/api/2025-10/control-plane/configure_index) and specify the `embed` object in the request body.
</Tip>

### From a backup

To create a dedicated read nodes index from a backup:

1. [Restore the backup](/guides/manage-data/restore-an-index). This creates a new on-demand index with the same data as the original.
2. If the restored index has multiple namespaces, [delete](/reference/api/latest/data-plane/deletenamespace) all of them except the one you want to keep. Dedicated read nodes currently only support [one namespace](#namespace-limits).
3. [Migrate the index to dedicated read nodes](#migrate-to-dedicated-read-nodes).

## Migrate to dedicated read nodes

### From a pod-based index

You cannot migrate a pod-based index directly to dedicated read nodes. First complete [Migrate a pod-based index to serverless](/guides/indexes/pods/migrate-a-pod-based-index-to-serverless), which creates a new on-demand index with your data.

If that index has multiple namespaces, consolidate to one namespace, or plan a different architecture. Dedicated read nodes currently support only a [single namespace](#namespace-limits).

### From an on-demand (serverless) index

To migrate an existing on-demand index to dedicated read nodes—including one you created by [migrating from pods](#from-a-pod-based-index)—follow these steps:

<Steps>
  <Step title="Create a backup of your index">
    [Create a backup](/guides/manage-data/back-up-an-index) of your index. If you later find that on-demand is preferable, you can restore the backup to a new on-demand index or [contact support](https://app.pinecone.io/organizations/-/settings/support/ticket) to migrate back.
  </Step>

  <Step title="Delete extra namespaces">
    If your index has multiple namespaces, [delete](/reference/api/latest/data-plane/deletenamespace) all of them except the one you want to keep. Dedicated read nodes currently only support a [single namespace](#namespace-limits).

    <Warning>
      If this is a production index, be sure to make a [backup](/guides/manage-data/back-up-an-index) before deleting namespaces. Or, if you need multiple namespaces, [contact support](https://app.pinecone.io/organizations/-/settings/support/ticket) to discuss early access to multi-namespace support for dedicated read nodes.
    </Warning>
  </Step>

  <Step title="Calculate your index size">
    [Calculate your index size](#index-size) to determine how many [shards](#number-of-shards) you need.
  </Step>

  <Step title="Migrate the index">
    To migrate the index, call [Configure an index](/reference/api/2025-10/control-plane/configure_index). In the request body, in the `spec.serverless.read_capacity` object, set the following fields:

    | Field                           | Value                                            | Notes                                                  |
    | :------------------------------ | :----------------------------------------------- | :----------------------------------------------------- |
    | **`mode`**                      | `Dedicated`                                      |                                                        |
    | **`dedicated.node_type`**       | `b1` or `t1`                                     | See [node types](#node-types)                          |
    | **`dedicated.scaling`**         | `Manual`                                         | Currently the only option                              |
    | **`dedicated.manual.shards`**   | Number of [shards](#number-of-shards) needed     | Minimum 1 shard; each shard provides 250 GB of storage |
    | **`dedicated.manual.replicas`** | Number of [replicas](#number-of-replicas) needed | Minimum 0 (this [pauses](#pause-an-index) the index)   |

    **Example**

    This example migrates an index to dedicated read nodes using `b1` nodes, one shard, and one replica:

    <CodeGroup>
      ```bash curl expandable theme={null}
      PINECONE_API_KEY="YOUR_API_KEY"
      INDEX_NAME="YOUR_INDEX_NAME"

      curl -X PATCH "https://api.pinecone.io/indexes/$INDEX_NAME" \
           -H "Accept: application/json" \
           -H "Content-Type: application/json" \
           -H "Api-Key: $PINECONE_API_KEY" \
           -H "X-Pinecone-Api-Version: 2025-10" \
           -d '{
                 "spec": {
                   "serverless": {
                     "read_capacity": {
                       "mode": "Dedicated",
                       "dedicated": {
                         "node_type": "b1",
                         "scaling": "Manual",
                         "manual": {
                           "shards": 1,
                           "replicas": 1
                         }
                       }
                     }
                   }
                 }
               }'
      ```
    </CodeGroup>

    Example response:

    <CodeGroup>
      ```jsonc curl expandable theme={null}
      {
        "name": "example-index-to-migrate",
        "vector_type": "dense",
        "metric": "cosine",
        "dimension": 1024,
        "status": {
          "ready": true,
          "state": "Ready"
        },
        "host": "example-index-to-migrate-1c6ab6aa.svc.aped-4627-b74a.pinecone.io",
        "spec": {
          "serverless": {
            "region": "us-east-1",
            "cloud": "aws",
            "read_capacity": {
              "mode": "Dedicated",
              "dedicated": {
                "node_type": "b1",
                "scaling": "Manual",
                "manual": {
                  "shards": 1, // <---- desired state
                  "replicas": 1
                }
              },
              "status": {
                "state": "Migrating",
                "current_shards": null, //<---- current state
                "current_replicas": null
              }
            }
          }
        },
        "deletion_protection": "disabled",
        "tags": null,
        "embed": {
          "model": "llama-text-embed-v2",
          "field_map": {
            "text": "text"
          },
          "dimension": 1024,
          "metric": "cosine",
          "write_parameters": {
            "dimension": 1024,
            "input_type": "passage",
            "truncate": "END"
          },
          "read_parameters": {
            "dimension": 1024,
            "input_type": "query",
            "truncate": "END"
          },
          "vector_type": "dense"
        }
      }
      ```
    </CodeGroup>

    The response includes two status fields:

    | Field                                            | Description                                                                |
    | :----------------------------------------------- | :------------------------------------------------------------------------- |
    | **`status.state`**                               | Overall index status (for example, `Initializing`, `Ready`, `Terminating`) |
    | **`spec.serverless.read_capacity.status.state`** | Read capacity status (`Migrating`, `Scaling`, `Ready`, `Error`)            |

    <Warning>
      If `status.state` is set to `Error`, the allocated number of shards was insufficient for the size of the index. Try again, adding more shards as needed.
    </Warning>
  </Step>

  <Step title="Monitor the migration">
    [Monitor](#check-the-status-of-a-change) the status of the migration. When the migration is complete, `spec.serverless.read_capacity.status.state` is `Ready`.
  </Step>

  <Step title="Monitor index performance">
    After migrating, monitor your index performance to verify that it meets expectations.
  </Step>
</Steps>

## Manage your index

The following sections describe how to manage a dedicated read nodes index using version `2025-10` of the Pinecone API.

<AccordionGroup>
  <Accordion title="Add a hosted embedding model">
    To upsert and search with text instead of vectors, you can configure your index to use a [hosted embedding model](/guides/index-data/create-an-index#embedding-models). To do this, call [Configure an index](/reference/api/2025-10/control-plane/configure_index) and provide an `embed` object in the request body. In this object:

    * For the `text` field, specify the name of the field in your data that contains the text to be embedded.
    * Specify a model whose dimension requirements match the dimensions of your index.

    **Example**

    Example request:

    <CodeGroup>
      ```bash curl expandable theme={null}
      PINECONE_API_KEY="YOUR_API_KEY"
      INDEX_NAME="YOUR_INDEX_NAME"

      curl -X PATCH "https://api.pinecone.io/indexes/$INDEX_NAME" \
           -H "Content-Type: application/json" \
           -H "Api-Key: $PINECONE_API_KEY" \
           -H "X-Pinecone-Api-Version: 2025-10" \
           -d '{
                 "embed": {
                   "field_map": {
                     "text": "chunk_text"
                   },
                   "model": "llama-text-embed-v2",
                   "read_parameters": {
                     "input_type": "query",
                     "truncate": "NONE"
                   },
                   "write_parameters": {
                     "input_type": "passage"
                   }
                 }
               }'
      ```
    </CodeGroup>

    Example response:

    <CodeGroup>
      ```json curl expandable theme={null}
      {
        "name": "example-dedicated-index",
        "vector_type": "dense",
        "metric": "cosine",
        "dimension": 1024,
        "status": {
          "ready": true,
          "state": "Ready"
        },
        "host": "example-dedicated-index-1c6ab6aa.svc.aped-4627-b74a.pinecone.io",
        "spec": {
          "serverless": {
            "region": "us-east-1",
            "cloud": "aws",
            "read_capacity": {
              "mode": "Dedicated",
              "dedicated": {
                "node_type": "b1",
                "scaling": "Manual",
                "manual": {
                  "shards": 2,
                  "replicas": 1
                }
              },
              "status": {
                "state": "Ready",
                "current_shards": 2,
                "current_replicas": 1
              }
            }
          }
        },
        "deletion_protection": "enabled",
        "tags": {
          "environment": "testing"
        },
        "embed": {
          "model": "llama-text-embed-v2",
          "field_map": {
            "text": "chunk_text"
          },
          "dimension": 1024,
          "metric": "cosine",
          "write_parameters": {
            "dimension": 1024,
            "input_type": "passage",
            "truncate": "END"
          },
          "read_parameters": {
            "dimension": 1024,
            "input_type": "query",
            "truncate": "NONE"
          },
          "vector_type": "dense"
        }
      }
      ```
    </CodeGroup>

    <Note>
      You can also create a dedicated read nodes index when calling [Create an index with integrated embedding](/reference/api/2025-10/control-plane/create_for_model). In the request body, use the `read_capacity` object to configure node type, shards, and replicas for dedicated read nodes.
    </Note>
  </Accordion>

  <Accordion title="Monitor index fullness">
    To check [index fullness](#index-fullness), call [Get index stats](/reference/api/2025-10/data-plane/describeindexstats).

    **Example**

    Example request:

    <CodeGroup>
      ```bash curl theme={null}
      # To get the unique host for an index,
      # see https://docs.pinecone.io/guides/manage-data/target-an-index
      PINECONE_API_KEY="YOUR_API_KEY"
      INDEX_HOST="YOUR_INDEX_HOST"

      curl -X GET "https://$INDEX_HOST/describe_index_stats" \
           -H "Api-Key: $PINECONE_API_KEY" \
           -H "X-Pinecone-Api-Version: 2025-10"
      ```
    </CodeGroup>

    Example response:

    <CodeGroup>
      ```json curl expandable theme={null}
      {
        "namespaces": {
          "__default__": {
            "vectorCount": 705000
          }
        },
        "indexFullness": 0.01,
        "totalVectorCount": 705000,
        "dimension": 1536,
        "metric": "cosine",
        "vectorType": "dense",
        "memoryFullness": 0.01,
        "storageFullness": 0.01
      }
      ```
    </CodeGroup>

    In the response, `indexFullness` describes how full the index is, on a scale of 0 to 1. It's set to the greater of `memoryFullness` and `storageFullness`.
  </Accordion>

  <Accordion title="Add or remove shards">
    To add or remove [shards](#shards), call [Configure an index](/reference/api/2025-10/control-plane/configure_index). This operation does not require downtime, but can take up to 30 minutes to complete. In the request body, set the following fields:

    | Field                                                       | Value                               | Notes                                 |
    | :---------------------------------------------------------- | :---------------------------------- | :------------------------------------ |
    | **`spec.serverless.read_capacity.mode`**                    | `Dedicated`                         |                                       |
    | **`spec.serverless.read_capacity.dedicated.scaling`**       | `Manual`                            |                                       |
    | **`spec.serverless.read_capacity.dedicated.manual.shards`** | Desired number of [shards](#shards) | Each shard provides 250 GB of storage |

    **Example**

    Example request:

    <CodeGroup>
      ```bash curl expandable theme={null}
      PINECONE_API_KEY="YOUR_API_KEY"
      INDEX_NAME="YOUR_INDEX_NAME"

      curl -X PATCH "https://api.pinecone.io/indexes/$INDEX_NAME" \
           -H "Accept: application/json" \
           -H "Content-Type: application/json" \
           -H "Api-Key: $PINECONE_API_KEY" \
           -H "X-Pinecone-Api-Version: 2025-10" \
           -d '{
                 "spec": {
                   "serverless": {
                     "read_capacity": {
                       "mode": "Dedicated",
                       "dedicated": {
                         "scaling": "Manual",
                         "manual": {
                           "shards": 3
                         }
                       }
                     }
                   }
                 }
               }'
      ```
    </CodeGroup>

    Example response:

    <CodeGroup>
      ```jsonc curl expandable theme={null}
      {
        "name": "example-dedicated-index",
        "vector_type": "dense",
        "metric": "cosine",
        "dimension": 1024,
        "status": {
          "ready": true,
          "state": "Ready"
        },
        "host": "example-dedicated-index-1c6ab6aa.svc.aped-4627-b74a.pinecone.io",
        "spec": {
          "serverless": {
            "region": "us-east-1",
            "cloud": "aws",
            "read_capacity": {
              "mode": "Dedicated",
              "dedicated": {
                "node_type": "b1",
                "scaling": "Manual",
                "manual": {
                  "shards": 3, // <---- desired state
                  "replicas": 1
                }
              },
              "status": {
                "state": "Scaling",
                "current_shards": 2, // <---- current state
                "current_replicas": 1
              }
            }
          }
        },
        "deletion_protection": "disabled",
        "tags": null,
        "embed": {
          "model": "llama-text-embed-v2",
          "field_map": {
            "text": "text"
          },
          "dimension": 1024,
          "metric": "cosine",
          "write_parameters": {
            "dimension": 1024,
            "input_type": "passage",
            "truncate": "END"
          },
          "read_parameters": {
            "dimension": 1024,
            "input_type": "query",
            "truncate": "END"
          },
          "vector_type": "dense"
        }
      }
      ```
    </CodeGroup>

    <Note>
      Configuration change limits:

      * You can make one configuration change every ten minutes, but you can batch multiple changes (node type, shards, and replicas) in a single request.
      * A new configuration change can only be initiated after the previous configuration change has completed.
      * Each configuration change can take up to 30 minutes to complete.
      * Read and write operations continue normally during configuration changes.
    </Note>
  </Accordion>

  <Accordion title="Add or remove replicas">
    To add or remove [replicas](#replicas), call [Configure an index](/reference/api/2025-10/control-plane/configure_index). This operation does not require downtime, but can take up to 30 minutes to complete. In the request body, set the following fields:

    | Field                                                         | Value                                   | Notes                                     |
    | :------------------------------------------------------------ | :-------------------------------------- | :---------------------------------------- |
    | **`spec.serverless.read_capacity.mode`**                      | `Dedicated`                             |                                           |
    | **`spec.serverless.read_capacity.dedicated.scaling`**         | `Manual`                                |                                           |
    | **`spec.serverless.read_capacity.dedicated.manual.replicas`** | Desired number of [replicas](#replicas) | Add replicas to increase query throughput |

    **Example**

    Example request:

    <CodeGroup>
      ```bash curl expandable theme={null}
      PINECONE_API_KEY="YOUR_API_KEY"
      INDEX_NAME="YOUR_INDEX_NAME"

      curl -X PATCH "https://api.pinecone.io/indexes/$INDEX_NAME" \
           -H "Accept: application/json" \
           -H "Content-Type: application/json" \
           -H "Api-Key: $PINECONE_API_KEY" \
           -H "X-Pinecone-Api-Version: 2025-10" \
           -d '{
                 "spec": {
                   "serverless": {
                     "read_capacity": {
                       "mode": "Dedicated",
                       "dedicated": {
                         "scaling": "Manual",
                         "manual": {
                           "replicas": 2
                         }
                       }
                     }
                   }
                 }
               }'
      ```
    </CodeGroup>

    Example response:

    <CodeGroup>
      ```jsonc curl expandable theme={null}
      {
        "name": "example-dedicated-index",
        "vector_type": "dense",
        "metric": "cosine",
        "dimension": 1024,
        "status": {
          "ready": true,
          "state": "Ready"
        },
        "host": "example-dedicated-index-1c6ab6aa.svc.aped-4627-b74a.pinecone.io",
        "spec": {
          "serverless": {
            "region": "us-east-1",
            "cloud": "aws",
            "read_capacity": {
              "mode": "Dedicated",
              "dedicated": {
                "node_type": "b1",
                "scaling": "Manual",
                "manual": {
                  "shards": 1,
                  "replicas": 2 // <---- desired state
                }
              },
              "status": {
                "state": "Scaling",
                "current_shards": 1,
                "current_replicas": 1 // <---- current state
              }
            }
          }
        },
        "deletion_protection": "disabled",
        "tags": null,
        "embed": {
          "model": "llama-text-embed-v2",
          "field_map": {
            "text": "text"
          },
          "dimension": 1024,
          "metric": "cosine",
          "write_parameters": {
            "dimension": 1024,
            "input_type": "passage",
            "truncate": "END"
          },
          "read_parameters": {
            "dimension": 1024,
            "input_type": "query",
            "truncate": "END"
          },
          "vector_type": "dense"
        }
      }
      ```
    </CodeGroup>

    <Note>
      Configuration change limits:

      * You can make one configuration change every ten minutes, but you can batch multiple changes (node type, shards, and replicas) in a single request.
      * A new configuration change can only be initiated after the previous configuration change has completed.
      * Each configuration change can take up to 30 minutes to complete.
      * Read and write operations continue normally during configuration changes.
    </Note>
  </Accordion>

  <Accordion title="Change node types">
    You can change node types in either direction (`b1` → `t1` or `t1` → `b1`). This operation does not require downtime, but can take up to 30 minutes to complete.

    <Note>
      The most predictable way to increase throughput is by increasing [replicas](#replicas).
    </Note>

    <Warning>
      `t1` nodes [cache more data in memory](#node-types) than `b1` nodes. Because of this, switching from `b1` to `t1` may require more shards.

      If your new configuration doesn't have enough shards, the configuration change will fail with an error telling you how many shards are required. Update the request and retry.

      In the meantime, your index will continue to function normally in its original configuration.
    </Warning>

    To change node types, call [Configure an index](/reference/api/2025-10/control-plane/configure_index). In the request body, set the following fields:

    | Field                                                   | Value        | Notes                         |
    | :------------------------------------------------------ | :----------- | :---------------------------- |
    | **`spec.serverless.read_capacity.mode`**                | `Dedicated`  |                               |
    | **`spec.serverless.read_capacity.dedicated.node_type`** | `b1` or `t1` | See [node types](#node-types) |

    **Example**

    Example request to change from `b1` to `t1`:

    <CodeGroup>
      ```bash curl expandable theme={null}
      PINECONE_API_KEY="YOUR_API_KEY"
      INDEX_NAME="YOUR_INDEX_NAME"

      curl -X PATCH "https://api.pinecone.io/indexes/$INDEX_NAME" \
           -H "Accept: application/json" \
           -H "Content-Type: application/json" \
           -H "Api-Key: $PINECONE_API_KEY" \
           -H "X-Pinecone-Api-Version: 2025-10" \
           -d '{
                 "spec": {
                   "serverless": {
                     "read_capacity": {
                       "mode": "Dedicated",
                       "dedicated": {
                         "node_type": "t1"
                       }
                     }
                   }
                 }
               }'
      ```
    </CodeGroup>

    Example response:

    <CodeGroup>
      ```json curl expandable theme={null}
      {
        "name": "example-dedicated-index",
        "vector_type": "dense",
        "metric": "cosine",
        "dimension": 1024,
        "status": {
          "ready": true,
          "state": "Ready"
        },
        "host": "example-dedicated-index-1c6ab6aa.svc.aped-4627-b74a.pinecone.io",
        "spec": {
          "serverless": {
            "region": "us-east-1",
            "cloud": "aws",
            "read_capacity": {
              "mode": "Dedicated",
              "dedicated": {
                "node_type": "t1",
                "scaling": "Manual",
                "manual": {
                  "shards": 1,
                  "replicas": 1
                }
              },
              "status": {
                "state": "Scaling",
                "current_shards": 1,
                "current_replicas": 1
              }
            }
          }
        },
        "deletion_protection": "disabled",
        "tags": null,
        "embed": {
          "model": "llama-text-embed-v2",
          "field_map": {
            "text": "text"
          },
          "dimension": 1024,
          "metric": "cosine",
          "write_parameters": {
            "dimension": 1024,
            "input_type": "passage",
            "truncate": "END"
          },
          "read_parameters": {
            "dimension": 1024,
            "input_type": "query",
            "truncate": "END"
          },
          "vector_type": "dense"
        }
      }
      ```
    </CodeGroup>

    <Note>
      Configuration change limits:

      * You can make one configuration change every ten minutes, but you can batch multiple changes (node type, shards, and replicas) in a single request.
      * A new configuration change can only be initiated after the previous configuration change has completed.
      * Each configuration change can take up to 30 minutes to complete.
      * Read and write operations continue normally during configuration changes.
    </Note>
  </Accordion>

  <Accordion title="Pause an index">
    To pause an index, [set the number of replicas](#add-or-remove-replicas) to 0. This operation can take up to 30 minutes to complete.

    <Note>
      While an index is paused, you cannot write to it or read from it. For a paused index, you're billed for storage, but not for node costs, reads, or writes.
    </Note>
  </Accordion>

  <Accordion title="Check the status of a configuration change">
    After making a configuration change to a dedicated read nodes index (changing shards, replicas, or node type), check the status of the change by calling [Describe an index](/reference/api/2025-10/control-plane/describe_index).

    **Example**

    Example request:

    <CodeGroup>
      ```bash curl theme={null}
      PINECONE_API_KEY="YOUR_API_KEY"
      INDEX_NAME="YOUR_INDEX_NAME"

      curl -X GET "https://api.pinecone.io/indexes/$INDEX_NAME" \
           -H "Api-Key: $PINECONE_API_KEY" \
           -H "X-Pinecone-Api-Version: 2025-10" 
      ```
    </CodeGroup>

    Example response (index scaling from one to two replicas):

    <CodeGroup>
      ```jsonc curl expandable theme={null}
      {
        "name": "example-dedicated-index",
        "vector_type": "dense",
        "metric": "cosine",
        "dimension": 1536,
        "status": {
          "ready": true,
          "state": "Ready"
        },
        "host": "example-dedicated-index-1c6ab6aa.svc.aped-4627-b74a.pinecone.io",
        "spec": {
          "serverless": {
            "region": "us-east-1",
            "cloud": "aws",
            "read_capacity": {
              "mode": "Dedicated",
              "dedicated": {
                "node_type": "b1",
                "scaling": "Manual",
                "manual": {
                  "shards": 1,
                  "replicas": 2 // <---- desired state
                }
              },
              "status": {
                "state": "Scaling", 
                "current_shards": 1,
                "current_replicas": 1 // <---- current state
              }
            }
          }
        },
        "deletion_protection": "enabled",
        "tags": {
          "tag0": "value0"
        }
      }
      ```
    </CodeGroup>

    The response includes two status fields:

    | Field                                            | Description                                                                |
    | :----------------------------------------------- | :------------------------------------------------------------------------- |
    | **`status.state`**                               | Overall index status (for example, `Initializing`, `Ready`, `Terminating`) |
    | **`spec.serverless.read_capacity.status.state`** | Read capacity status (`Migrating`, `Scaling`, `Ready`, `Error`)            |

    When changing node types, shards, or replicas, monitor the read capacity status (`spec.serverless.read_capacity.status.state`). Possible values:

    | State           | Description                                                                                                                                                                                   |
    | :-------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | **`Ready`**     | The change is complete and the index is ready to serve queries at full capacity.                                                                                                              |
    | **`Scaling`**   | A change to the number of shards or replicas is in progress.                                                                                                                                  |
    | **`Migrating`** | A change to the node type or read capacity <Tooltip>mode</Tooltip> is in progress.                                                                                                            |
    | **`Error`**     | The operation failed. For migrations to dedicated, this typically means you didn't allocate enough shards for your index size. Check `error_message` for details, and retry with more shards. |

    <Note>
      During changes to shards, replicas, and node type, the index-level status (`status.state`) remains `Ready`. This is because the index can handle reads and writes while its dedicated read capacity scales.
    </Note>

    <Note>
      Configuration change limits:

      * You can make one configuration change every ten minutes, but you can batch multiple changes (node type, shards, and replicas) in a single request.
      * A new configuration change can only be initiated after the previous configuration change has completed.
      * Each configuration change can take up to 30 minutes to complete.
      * Read and write operations continue normally during configuration changes.
    </Note>
  </Accordion>

  <Accordion title="Migrate from dedicated to on-demand">
    You cannot directly convert a dedicated read nodes index to on-demand with the API. Instead, you can migrate your data by [backing up your index](/guides/manage-data/back-up-an-index) and then [restoring it into a new serverless index](/guides/manage-data/restore-an-index) without dedicated read nodes enabled.

    1. [Create a backup](/guides/manage-data/back-up-an-index) of your dedicated read nodes index.
    2. [Create a new index from the backup](/guides/manage-data/restore-an-index), without specifying dedicated read node configuration.
    3. Verify the new on-demand index and update your application to use it.
    4. Delete the old dedicated read nodes index.

    If you have concerns or need assistance, [contact support](https://app.pinecone.io/organizations/-/settings/support/ticket).
  </Accordion>
</AccordionGroup>

## Limits

The following limits apply to dedicated read nodes:

<AccordionGroup>
  <Accordion title="Read limits">
    Dedicated read nodes indexes are not subject to [read-operation rate limits](/reference/api/database-limits#rate-limits), like on-demand indexes are. However, if your query rate exceeds the compute capacity of your index, you may observe decreased query throughput. In such cases, consider [adding replicas](#add-or-remove-replicas) to increase compute resources, or use [query-time search parameters](#query-time-search-parameters) to reduce per-query compute and increase throughput without adding replicas.
  </Accordion>

  <Accordion title="Write limits">
    On dedicated read nodes indexes, write operations (upsert, update, delete) have the same [rate limits](/reference/api/database-limits#rate-limits) as on-demand indexes.

    Writes that would cause your index to exceed its storage capacity are blocked. In such cases, consider [adding shards](#add-or-remove-shards) to increase available storage. To determine how close to the write limit you are, [check index fullness](#monitor-index-fullness).
  </Accordion>

  <Accordion title="Namespace limits">
    Currently, dedicated read nodes indexes only support a single namespace. However, multi-namespace support is coming soon. For early access, [contact support](https://app.pinecone.io/organizations/-/settings/support/ticket).
  </Accordion>

  <Accordion title="Shard, replica, and node limits">
    **Shards**

    The minimum number of [shards](#shards) per index is 1.

    **Replicas**

    The minimum number of [replicas](#replicas) per index is 0, which [pauses the index](#pause-an-index).

    **Nodes**

    The maximum number of [nodes](#node-types) per project is 20. This is a **project** limit, not an index limit.

    To calculate your total node count, multiply `shards × replicas` for each of your project's indexes, and then sum the results. This total must not exceed 20. For example, if you have two indexes that each have two shards and three replicas, your total node count is `(2 × 3) + (2 × 3) = 12` nodes.

    To increase your project's node limit, [contact support](https://app.pinecone.io/organizations/-/settings/support/ticket).

    <Note>
      Configuration change limits:

      * You can make one configuration change every ten minutes, but you can batch multiple changes (node type, shards, and replicas) in a single request.
      * A new configuration change can only be initiated after the previous configuration change has completed.
      * Each configuration change can take up to 30 minutes to complete.
      * Read and write operations continue normally during configuration changes.
    </Note>
  </Accordion>

  <Accordion title="memoryFullness">
    `memoryFullness` is an approximation and doesn't yet account for metadata. For more information, see [Index fullness](#index-fullness).
  </Accordion>

  <Accordion title="Migrating from dedicated to on-demand">
    To migrate an index from dedicated to on-demand, [contact support](https://app.pinecone.io/organizations/-/settings/support/ticket). This cannot be done with the API.
  </Accordion>
</AccordionGroup>

## Cost

<Note>
  For the latest pricing information, see the [Pinecone pricing page](https://www.pinecone.io/pricing/).
</Note>

The cost of an index has three components: read costs, write costs, and storage costs.

On-demand and dedicated read nodes share infrastructure for writes and storage, so these costs are the same. However, dedicated read nodes provision dedicated hardware for read operations (query, fetch, list), which changes how read costs are calculated.

| Cost component    | On-demand                                                                                                | Dedicated read nodes                                                                               |
| :---------------- | :------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------- |
| **Read costs**    | [Usage-based](/guides/manage-cost/understanding-cost#read-units): 1 RU per 1 GB namespace size per query | Fixed hourly rate: Based on [node type](#node-types), [shards](#shards), and [replicas](#replicas) |
| **Write costs**   | [Usage-based](/guides/manage-cost/understanding-cost#write-units)                                        | [Usage-based](/guides/manage-cost/understanding-cost#write-units) (same as on-demand)              |
| **Storage costs** | [Usage-based](/guides/manage-cost/understanding-cost#storage)                                            | [Usage-based](/guides/manage-cost/understanding-cost#storage) (same as on-demand)                  |

<Note>
  If you use a hosted model for search or reranking, there are additional [inference costs](https://www.pinecone.io/pricing).
</Note>

<AccordionGroup>
  <Accordion title="Calculate dedicated read nodes costs">
    To calculate the total cost of a dedicated read nodes index, use this formula:

    ```
    (Node rate × shards × replicas) + storage costs + write costs
    ```

    | Term              | Description                                                                                                                                           |
    | :---------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- |
    | **Node rate**     | Monthly rate for the [node type](#node-types) (`b1` or `t1`), which varies by cloud region. See [Pinecone pricing](https://www.pinecone.io/pricing/). |
    | **Shards**        | Number of [shards](#shards) allocated                                                                                                                 |
    | **Replicas**      | Number of [replicas](#replicas) allocated                                                                                                             |
    | **Storage costs** | [Usage-based](/guides/manage-cost/understanding-cost#storage), same as on-demand                                                                      |
    | **Write costs**   | [Usage-based](/guides/manage-cost/understanding-cost#write-units), same as on-demand                                                                  |

    <Tip>
      For help estimating costs, use the [Pinecone pricing calculator](https://www.pinecone.io/pricing/estimate/) or [contact us](https://www.pinecone.io/contact/).
    </Tip>

    **Example:** If the rate for `b1` nodes on `aws-us-east-1` is \$336.42/month (\$0.46/hour), an index with two shards and two replicas would cost:

    ```
    336.42 × 2 × 2 = $1,345.68/month, plus storage and write costs
    ```
  </Accordion>
</AccordionGroup>


# Implement multitenancy
Source: https://docs.pinecone.io/guides/index-data/implement-multitenancy

Implement multitenancy in Pinecone with one namespace per tenant on a serverless index to isolate customer data for SaaS RAG or semantic search apps.

[Multitenancy](https://en.wikipedia.org/wiki/Multitenancy) is a software architecture where a single instance of a system serves multiple customers, or tenants, while ensuring data isolation between them for privacy and security.

This page shows you how to implement multitenancy in Pinecone using a **serverless index with one namespace per tenant**.

<Note>
  For design guidance on choosing between namespaces, metadata filtering, and other approaches, see [Design for multi-tenancy](/guides/index-data/data-modeling#design-for-multi-tenancy).
</Note>

<Note>
  [Namespaces per serverless index](/reference/api/database-limits#namespaces-per-serverless-index) vary by plan. On the Standard and Enterprise plans, Pinecone can accommodate million-scale namespaces and beyond for specific use cases. If your application requires more than 100,000 namespaces, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).
</Note>

## How it works

<img />

<img />

In Pinecone, an [index](/guides/index-data/indexing-overview) is the highest-level organizational unit of data, where you define the dimension of vectors to be stored in the index and the measure of similarity to be used when querying the index.

Within an index, records are stored in [namespaces](/guides/index-data/indexing-overview#namespaces), and all [upserts](/guides/index-data/upsert-data), [queries](/guides/search/search-overview), and other data read and write operations always target one namespace.

This structure makes it easy to implement multitenancy. For example, for an AI-powered SaaS application where you need to isolate the data of each customer, you would assign each customer to a namespace and target their writes and queries to that namespace (diagram above).

In cases where you have different workload patterns (e.g., RAG and semantic search), you would use a different index for each workload, with one namespace per customer in each index:

<img />

<img />

<Accordion title="Understand the benefits">
  * **Tenant isolation:** In the [serverless architecture](/guides/get-started/database-architecture), each namespace is stored separately, so using namespaces provides physical isolation of data between tenants/customers. This reduces the risk of application bugs that could query the wrong tenant's data.

  * **No noisy neighbors:** Reads and writes always target a single namespace, so the behavior of one tenant/customer does not affect other tenants/customers.

  * **No maintenance effort:** Serverless indexes scale automatically based on usage; you don't configure or manage any compute or storage resources.

  * **Cost efficiency:** Query cost is based on namespace size (1 RU per 1 GB). With 100 tenants of 1 GB each, querying one tenant's namespace costs 1 RU. Using metadata filtering in a single 100 GB namespace would cost 100 RUs for the same query, because it scans all data regardless of filters.

  * **Simple tenant offboarding:** To offboard a tenant/customer, you just [delete the relevant namespace](/guides/manage-data/delete-data#delete-all-records-from-a-namespace). This is a lightweight and almost instant operation.
</Accordion>

## 1. Create a serverless index

Based on a [breakthrough architecture](/guides/get-started/database-architecture), serverless indexes scale automatically based on usage, and you pay only for the amount of data stored and operations performed. Combined with the isolation of tenant data using namespaces (next step), serverless indexes are ideal for multitenant use cases.

To [create a serverless index](/guides/index-data/create-an-index#create-a-serverless-index), use the `spec` parameter to define the cloud and region where the index should be deployed. For Python, you also need to import the `ServerlessSpec` class.

<CodeGroup>
  ```Python Python theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone
  from pinecone import ServerlessSpec

  pc = Pinecone(api_key="YOUR_API_KEY")

  pc.create_index(
    name="multitenant-app",
    dimension=8,
    metric="cosine",
    spec=ServerlessSpec(
      cloud="aws",
      region="us-east-1"
    )
  )
  ```

  ```JavaScript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone'

  const pc = new Pinecone({
    apiKey: 'YOUR_API_KEY'
  });

  await pc.createIndex({
    name: 'multitenant-app',
    dimension: 8,
    metric: 'cosine',
    spec: {
      serverless: {
        cloud: 'aws',
        region: 'us-east-1'
      }
    }
  });
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Pinecone;

  public class CreateServerlessIndexExample {
      public static void main(String[] args) {
          Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build();
          pc.createServerlessIndex("multitenant-app", "cosine", 8, "aws", "us-east-1");
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "encoding/json"
      "fmt"
      "log"

      "github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func prettifyStruct(obj interface{}) string {
    	bytes, _ := json.MarshalIndent(obj, "", "  ")
      return string(bytes)
  }

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

      // Serverless index
      indexName := "multi-tenant-app"
      vectorType := "dense"
      dimension := int32(8)
      metric := pinecone.Cosine
      deletionProtection := pinecone.DeletionProtectionDisabled

      idx, err := pc.CreateServerlessIndex(ctx, &pinecone.CreateServerlessIndexRequest{
          Name:               indexName,
          VectorType:         &vectorType,
          Dimension:          &dimension,
          Metric:             &metric,
          Cloud:              pinecone.Aws,
          Region:             "us-east-1",
          DeletionProtection: &deletionProtection,
      })
      if err != nil {
          log.Fatalf("Failed to create serverless index: %v", err)
      } else {
          fmt.Printf("Successfully created serverless index: %v", idx.Name)
      }
  }
  ```

  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"

  curl -s "https://api.pinecone.io/indexes" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2025-10" \
    -d '{
           "name": "multitenant-app",
           "dimension": 8,
           "metric": "cosine",
           "spec": {
              "serverless": {
                 "cloud": "aws",
                 "region": "us-east-1"
              }
           }
        }'
  ```
</CodeGroup>

## 2. Isolate tenant data

In a multitenant solution, you need to isolate data between tenants. To achieve this in Pinecone, use one namespace per tenant. In the [serverless architecture](/guides/get-started/database-architecture), each namespace is stored separately, so this approach ensures physical isolation of each tenant's data.

To [create a namespace for a tenant](/guides/index-data/indexing-overview#namespaces#creating-a-namespace), specify the `namespace` parameter when first [upserting](/guides/index-data/upsert-data) the tenant's records. For example, the following code upserts records for `tenant1` and `tenant2` into the `multitenant-app` index:

<CodeGroup>
  ```Python Python theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")
  index = pc.Index("multitenant-app")

  index.upsert(
    vectors=[
      {"id": "A", "values": [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1]},
      {"id": "B", "values": [0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2]},
      {"id": "C", "values": [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3]},
      {"id": "D", "values": [0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4]}
    ],
    namespace="tenant1"
  )

  index.upsert(
    vectors=[
      {"id": "E", "values": [0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5]},
      {"id": "F", "values": [0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6]},
      {"id": "G", "values": [0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7]},
      {"id": "H", "values": [0.8, 0.8, 0.8, 0.8, 0.8, 0.8, 0.8, 0.8]}
    ],
    namespace="tenant2"
  )
  ```

  ```JavaScript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone'

  const pc = new Pinecone({ apiKey: "YOUR_API_KEY" });
  const index = pc.index("multitenant-app");

  await index.namespace("tenant1").upsert([
    {
      "id": "A", 
      "values": [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1]
    },
    {
      "id": "B", 
      "values": [0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2]
    },
    {
      "id": "C", 
      "values": [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3]
    },
    {
      "id": "D", 
      "values": [0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4]
    }
  ]);

  await index.namespace("tenant2").upsert([
    {
      "id": "E", 
      "values": [0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5]
    },
    {
      "id": "F", 
      "values": [0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6]
    },
    {
      "id": "G", 
      "values": [0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7]
    },
    {
      "id": "H", 
      "values": [0.8, 0.8, 0.8, 0.8, 0.8, 0.8, 0.8, 0.8]
    }
  ]);
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Index;
  import io.pinecone.clients.Pinecone;

  import java.util.Arrays;
  import java.util.List;

  public class UpsertExample {
      public static void main(String[] args) {
          Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build();
          String indexName = "multitenant-app";
          Index index = pc.getIndexConnection(indexName);
          List<Float> values1 = Arrays.asList(0.1f, 0.1f, 0.1f, 0.1f, 0.1f, 0.1f, 0.1f, 0.1f);
          List<Float> values2 = Arrays.asList(0.2f, 0.2f, 0.2f, 0.2f, 0.2f, 0.2f, 0.2f, 0.2f);
          List<Float> values3 = Arrays.asList(0.3f, 0.3f, 0.3f, 0.3f, 0.3f, 0.3f, 0.3f, 0.3f);
          List<Float> values4 = Arrays.asList(0.4f, 0.4f, 0.4f, 0.4f, 0.4f, 0.4f, 0.4f, 0.4f);
          List<Float> values5 = Arrays.asList(0.5f, 0.5f, 0.5f, 0.5f, 0.5f, 0.5f, 0.5f, 0.5f);
          List<Float> values6 = Arrays.asList(0.6f, 0.6f, 0.6f, 0.6f, 0.6f, 0.6f, 0.6f, 0.6f);
          List<Float> values7 = Arrays.asList(0.7f, 0.7f, 0.7f, 0.7f, 0.7f, 0.7f, 0.7f, 0.7f);
          List<Float> values8 = Arrays.asList(0.8f, 0.8f, 0.8f, 0.8f, 0.8f, 0.8f, 0.8f, 0.8f);

          index.upsert("A", values1, "tenant1");
          index.upsert("B", values2, "tenant1");
          index.upsert("C", values3, "tenant1");
          index.upsert("D", values4, "tenant1");
          index.upsert("E", values5, "tenant2");
          index.upsert("F", values6, "tenant2");
          index.upsert("G", values7, "tenant2");
          index.upsert("H", values8, "tenant2");
      }
  }
  ```

  ```go Go theme={null}
  // Add to the main function:
  idx, err := pc.DescribeIndex(ctx, indexName)
  if err != nil {
      log.Fatalf("Failed to describe index \"%v\": %v", idx.Name, err)
  }

  idxConnection1, err := pc.Index(pinecone.NewIndexConnParams{Host: idx.Host, Namespace: "tenant1"})
  if err != nil {
      log.Fatalf("Failed to create IndexConnection1 for Host %v: %v", idx.Host, err)
  }

  // This reuses the gRPC connection of idxConnection1 while targeting a different namespace
  idxConnection2 := idxConnection1.WithNamespace("tenant2")

  vectors1 := []*pinecone.Vector{
      {
          Id:     "A",
          Values: []float32{0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1},
      },
      {
          Id:     "B",
          Values: []float32{0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2},
      },
      {
          Id:     "C",
          Values: []float32{0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3},
      },   
      {
          Id:     "D",
          Values: []float32{0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4},
      },   
  }

  vectors2 := []*pinecone.Vector{
      {
          Id:     "E",
          Values: []float32{0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5},
      },
      {
          Id:     "F",
          Values: []float32{0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6},
      },
      {
          Id:     "G",
          Values: []float32{0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7},
      },   
      {
          Id:     "H",
          Values: []float32{0.8, 0.8, 0.8, 0.8, 0.8, 0.8, 0.8, 0.8},
      },   
  }

  count1, err := idxConnection1.UpsertVectors(ctx, vectors1)
  if err != nil {
      log.Fatalf("Failed to upsert vectors: %v", err)
  } else {
      fmt.Printf("Successfully upserted %d vector(s)!\n", count1)
  }

  count2, err := idxConnection2.UpsertVectors(ctx, vectors2)
  if err != nil {
      log.Fatalf("Failed to upsert vectors: %v", err)
  } else {
      fmt.Printf("Successfully upserted %d vector(s)!\n", count2)
  }
  ```

  ```bash curl theme={null}
  # The `POST` requests below uses the unique endpoint for an index.
  # See https://docs.pinecone.io/guides/manage-data/target-an-index for details.
  PINECONE_API_KEY="YOUR_API_KEY"
  INDEX_HOST="INDEX_HOST"

  curl "https://$INDEX_HOST/vectors/upsert" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H 'Content-Type: application/json' \
    -H "X-Pinecone-Api-Version: 2025-10" \
    -d '{
      "vectors": [
        {
          "id": "A", 
          "values": [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1]
        },
        {
          "id": "B", 
          "values": [0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2]
        },
        {
          "id": "C", 
          "values": [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3]
        },
        {
          "id": "D", 
          "values": [0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4]
        }
      ],
      "namespace": "tenant1"
    }'

  curl "https://$INDEX_HOST/vectors/upsert" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H 'Content-Type: application/json' \
    -H "X-Pinecone-Api-Version: 2025-10" \
    -d '{
      "vectors": [
        {
          "id": "E", 
          "values": [0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5]
        },
        {
          "id": "F", 
          "values": [0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6]
        },
        {
          "id": "G", 
          "values": [0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7]
        },
        {
          "id": "H", 
          "values": [0.8, 0.8, 0.8, 0.8, 0.8, 0.8, 0.8, 0.8]
        }
      ],
      "namespace": "tenant2"
    }'
  ```
</CodeGroup>

When upserting additional records for a tenant, or when [updating](/guides/manage-data/update-data) or [deleting](/guides/manage-data/delete-data) records for a tenant, specify the tenant's `namespace`. For example, the following code updates the dense vector value of record `A` in `tenant1`:

<CodeGroup>
  ```Python Python theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")
  index = pc.Index("multitenant-app")

  index.update(id="A", values=[0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8], namespace="tenant1")
  ```

  ```JavaScript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone'

  const pc = new Pinecone({ apiKey: "YOUR_API_KEY" });
  const index = pc.index("multitenant-app");

  await index.namespace('tenant1').update({
   	id: 'A',
   	values: [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8]
  });
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Index;
  import io.pinecone.clients.Pinecone;
  import io.pinecone.proto.UpdateResponse;

  import java.util.Arrays;
  import java.util.List;

  public class UpdateExample {
      public static void main(String[] args) {
          Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build();
          Index index = pc.getIndexConnection("multitenant-app");
          List<Float> values = Arrays.asList(0.1f, 0.2f, 0.3f, 0.4f, 0.5f, 0.6f, 0.7f, 0.8f);
          UpdateResponse updateResponse = index.update("A", values, null, "tenant1", null, null);
          System.out.println(updateResponse);
      }
  }
  ```

  ```go Go theme={null}
  // Add to the main function:
  idxConn1.UpdateVector(ctx, &pinecone.UpdateVectorRequest{
      Id:     "A",
      Values: []float32{0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8},
  })
  if err != nil {
      log.Fatalf("Failed to update vector with ID %v: %v", id, err)
  }
  ```

  ```bash curl theme={null}
  # The `POST` request below uses the unique endpoint for an index.
  # See https://docs.pinecone.io/guides/manage-data/target-an-index for details.
  PINECONE_API_KEY="YOUR_API_KEY"
  INDEX_HOST="INDEX_HOST"

  curl "https://$INDEX_HOST/vectors/update" \
  	-H "Api-Key: $PINECONE_API_KEY" \
  	-H 'Content-Type: application/json' \
    -H "X-Pinecone-Api-Version: 2025-10" \
  	-d '{
  			"id": "A",
  			"values": [01., 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8],
  			"namespace": "tenant1"
  		}'
  ```
</CodeGroup>

## 3. Query tenant data

In a multitenant solution, you need to ensure that the queries of one tenant do not affect the experience of other tenants/customers. To achieve this in Pinecone, target each tenant's [queries](/guides/search/search-overview) at the namespace for the tenant.

For example, the following code queries only `tenant2` for the 3 vectors that are most similar to an example query vector:

<CodeGroup>
  ```python Python theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")
  index = pc.Index("multitenant-app")

  query_results = index.query(
      namespace="tenant2",
      vector=[0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7],
      top_k=3,
      include_values=True
  )

  print(query_results)

  # Returns:
  # {'matches': [{'id': 'F',
  #               'score': 1.00000012,
  #               'values': [0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6]},
  #              {'id': 'G',
  #               'score': 1.0,
  #               'values': [0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7]},
  #              {'id': 'E',
  #               'score': 1.0,
  #               'values': [0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5]}],
  #  'namespace': 'tenant2',
  #  'usage': {'read_units': 6}}
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone'

  const pc = new Pinecone({ apiKey: "YOUR_API_KEY" });
  const index = pc.index("multitenant-app");

  const queryResponse = await index.namespace("tenant2").query({
    topK: 3,
    vector: [0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7],
    includeValues: true
  });

  console.log(queryResponse);

  // Returns:
  {
    "matches": [
      {
        "id": "F",
        "score": 1.00000012,
        "values": [
          0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6
        ]
      },
      {
        "id": "E",
        "score": 1,
        "values": [ 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5
        ]
      },
      {
        "id": "G",
        "score": 1,
        "values": [
          0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7
        ]
      }
    ],
    "namespace": "tenant2",
    "usage": {
      "readUnits": 6
    }
  }
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Index;
  import io.pinecone.clients.Pinecone;
  import io.pinecone.unsigned_indices_model.QueryResponseWithUnsignedIndices;

  import java.util.Arrays;
  import java.util.List;

  public class QueryExample {
      public static void main(String[] args) {
          Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build();
          String indexName = "multitenant-app";
          Index index = pc.getIndexConnection(indexName);
          List<Float> queryVector = Arrays.asList(0.7f, 0.7f, 0.7f, 0.7f, 0.7f, 0.7f, 0.7f, 0.7f);
          QueryResponseWithUnsignedIndices queryResponse = index.query(3, queryVector2, null, null, null, "tenant2", null, true, false);
          System.out.println(queryResponse);
      }
  }

  // Results:
  // class QueryResponseWithUnsignedIndices {
  //     matches: [ScoredVectorWithUnsignedIndices {
  //         score: 1.00000012
  //         id: F
  //         values: [0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6]
  //         metadata: 
  //         sparseValuesWithUnsignedIndices: SparseValuesWithUnsignedIndices {
  //             indicesWithUnsigned32Int: []
  //             values: []
  //         }
  //     }, ScoredVectorWithUnsignedIndices {
  //         score: 1
  //         id: E
  //         values: [0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5]
  //         metadata: 
  //         sparseValuesWithUnsignedIndices: SparseValuesWithUnsignedIndices {
  //             indicesWithUnsigned32Int: []
  //             values: []
  //         }
  //     }, ScoredVectorWithUnsignedIndices {
  //         score: 0.07999992
  //         id: G
  //         values: [0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7]
  //         metadata: 
  //         sparseValuesWithUnsignedIndices: SparseValuesWithUnsignedIndices {
  //             indicesWithUnsigned32Int: []
  //             values: []
  //         }
  //     }]
  //     namespace: tenant2
  //     usage: read_units: 6
  // }
  ```

  ```go Go theme={null}
  // Add to the main function:
  queryVector := []float32{0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7}

  res, err := idxConnection2.QueryByVectorValues(ctx, &pinecone.QueryByVectorValuesRequest{
      Vector:        queryVector,
      TopK:          3,
      IncludeValues: true,
  })
  if err != nil {
      log.Fatalf("Error encountered when querying by vector: %v", err)
  } else {
      fmt.Printf(prettifyStruct(res))
  }

  // Returns:
  // {
  //   "matches": [
  //     {
  //       "vector": {
  //         "id": "F",
  //         "values": [
  //           0.6,
  //           0.6,
  //           0.6,
  //           0.6,
  //           0.6,
  //           0.6,
  //           0.6,
  //           0.6
  //         ]
  //       },
  //       "score": 1.0000001
  //     },
  //     {
  //       "vector": {
  //         "id": "G",
  //         "values": [
  //           0.7,
  //           0.7,
  //           0.7,
  //           0.7,
  //           0.7,
  //           0.7,
  //           0.7,
  //           0.7
  //         ]
  //       },
  //       "score": 1
  //     },
  //     {
  //       "vector": {
  //         "id": "H",
  //         "values": [
  //           0.8,
  //           0.8,
  //           0.8,
  //           0.8,
  //           0.8,
  //           0.8,
  //           0.8,
  //           0.8
  //         ]
  //       },
  //       "score": 1
  //     }
  //   ],
  //   "usage": {
  //     "read_units": 6
  //   }
  // }
  ```

  ```shell curl theme={null}
  # The `POST` requests below uses the unique endpoint for an index.
  # See https://docs.pinecone.io/guides/manage-data/target-an-index for details.
  PINECONE_API_KEY="YOUR_API_KEY"
  INDEX_HOST="INDEX_HOST"

  curl "https://$INDEX_HOST/query" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H 'Content-Type: application/json' \
    -H "X-Pinecone-Api-Version: 2025-10" \
    -d '{
      "namespace": "tenant2",
      "vector": [0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7],
      "topK": 3,
      "includeValues": true
    }'
  #
  # Output:
  # {
  #   "matches": [
  #     {
  #       "id": "F",
  #       "score": 1.00000012,
  #       "values": [0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6]
  #     },
  #     {
  #       "id": "E",
  #       "score": 1,
  #       "values": [0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5]
  #     },
  #     {
  #       "id": "G",
  #       "score": 1,
  #       "values": [0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7]
  #     }
  #   ],
  #   "namespace": "tenant2",
  #   "usage": {"read_units": 6}
  # }
  ```
</CodeGroup>

## 4. Offboard a tenant

In a multitenant solution, you also need it to be quick and easy to offboard a tenant and delete all of its records. To achieve this in Pinecone, you just [delete the namespace](/guides/manage-data/delete-data#delete-an-entire-namespace) for the specific tenant.

For example, the following code deletes the namespace and all records for `tenant1`:

<CodeGroup>
  ```Python Python theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")
  index = pc.Index("multitenant-app")

  index.delete(delete_all=True, namespace='tenant1')
  ```

  ```JavaScript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone'

  const pc = new Pinecone({ apiKey: "YOUR_API_KEY" });
  const index = pc.index("multitenant-app");

  await index.namespace('tenant1').deleteAll();
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Index;
  import io.pinecone.clients.Pinecone;

  public class DeleteVectorsExample {
      public static void main(String[] args) {
          Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build();
          Index index = pc.getIndexConnection("multitenant-app");
          index.deleteAll("tenant1");
      }
  }
  ```

  ```go Go theme={null}
  // Add to the main function:
  idxConnection1.DeleteAllVectorsInNamespace(ctx)
  if err != nil {
      log.Fatalf("Failed to delete vectors in namespace \"%v\": %v", idxConnection2.Namespace, err)
  }
  ```

  ```bash curl theme={null}
  # The `POST` request below uses the unique endpoint for an index.
  # See https://docs.pinecone.io/guides/manage-data/target-an-index for details.
  PINECONE_API_KEY="YOUR_API_KEY"
  INDEX_HOST="INDEX_HOST"
  curl "https://$INDEX_HOST/vectors/delete" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H 'Content-Type: application/json' \
    -H "X-Pinecone-Api-Version: 2025-10" \
    -d '{
      "deleteAll": true,
      "namespace": "tenant1"
    }
  '
  ```
</CodeGroup>

## Alternative: Metadata filtering

When tenant isolation is not a strict requirement, or when you need to query across multiple tenants simultaneously, you can store all records in a single namespace and use metadata fields to assign records to tenants/customers. At query time, you can then [filter by metadata](/guides/index-data/indexing-overview#metadata).

<Warning>
  This approach has significant performance and cost tradeoffs compared to using namespaces:

  * Higher query costs: Queries scan the entire namespace regardless of filters, so you pay for scanning all tenants' data even though results are filtered to one tenant.
  * Slower performance: Large namespaces increase query latency, and large filters add network overhead on the request side.
  * Filter size limits: Each `$in` or `$nin` operator is limited to 10,000 values. Exceeding this limit will cause requests to fail. See [Metadata filter limits](/reference/api/database-limits#metadata-filter-limits).

  Anti-pattern: Avoid filtering by large lists of individual user IDs. Instead, use access control groups (organization, project, role), namespaces, or post-filter client-side (for semantic search).

  For detailed guidance on choosing between namespaces and metadata filtering, see [Design for multi-tenancy](/guides/index-data/data-modeling#design-for-multi-tenancy).
</Warning>

For more background on this approach, see [Multitenancy in Vector Databases](https://www.pinecone.io/learn/series/vector-databases-in-production-for-busy-engineers/vector-database-multi-tenancy/).


# Import records
Source: https://docs.pinecone.io/guides/index-data/import-data

Import large datasets efficiently from Amazon S3, Google Cloud Storage, or Azure Blob Storage into Pinecone serverless indexes using object storage.

Importing from object storage is the most efficient and cost-effective way to load large numbers of records into an index.

To run through this guide in your browser, see the [Bulk import colab notebook](https://colab.research.google.com/github/pinecone-io/examples/blob/master/docs/pinecone-import.ipynb).

<Note>
  This feature is available on [Standard and Enterprise plans](https://www.pinecone.io/pricing/).
</Note>

## Before you import

Before you can import records, ensure you have a serverless index, a storage integration, and data formatted in a Parquet file and uploaded to an Amazon S3 bucket, Google Cloud Storage bucket, or Azure Blob Storage container.

### Create an index

[Create a serverless index](/guides/index-data/create-an-index) for your data.

Be sure to create your index on a cloud that supports importing from the object storage you want to use:

|                                       | …to an **AWS** index | …to a **GCP** index | …to an **Azure** index |
| ------------------------------------- | :------------------: | :-----------------: | :--------------------: |
| Import from **AWS S3**…               |           ✅          |          ❌          |            ❌           |
| Import from **Google Cloud Storage**… |           ✅          |          ✅          |            ✅           |
| Import from **Azure Blob Storage**…   |           ✅          |          ✅          |            ✅           |

### Add a storage integration

To import records from a public data source, a storage integration is not required. However, to import records from a secure data source, you must create an integration to allow Pinecone access to data in your object storage. See the following guides:

* [Integrate with Amazon S3](/guides/operations/integrations/integrate-with-amazon-s3)
* [Integrate with Google Cloud Storage](/guides/operations/integrations/integrate-with-google-cloud-storage)
* [Integrate with Azure Blob Storage](/guides/operations/integrations/integrate-with-azure-blob-storage)

### Prepare your data

1. In your Amazon S3 bucket, Google Cloud Storage bucket, or Azure Blob Storage container, create an import directory containing a subdirectory for each namespace you want to import into. The namespaces must not yet exist in your index.

   For example, to import data into the namespaces `example_namespace1` and `example_namespace2`, your directory structure would look like this:

   ```
   <BUCKET_OR_CONTAINER_NAME>/
   --/<IMPORT_DIR>/
   ----/example_namespace1/
   ----/example_namespace2/
   ```

   <Tip>
     To import into the default namespace, use a subdirectory called `__default__`. The default namespace must be empty.
   </Tip>

2. For each namespace, create one or more Parquet files defining the records to import.

   Parquet files must contain specific columns, depending on the index type:

   <Tabs>
     <Tab title="Index of dense vectors">
       To import into a namespace in an [index of dense vectors](/guides/index-data/indexing-overview#indexes-with-dense-vectors), the Parquet file must contain the following columns:

       | Column name | Parquet type  | Description                                                                                                                     |
       | ----------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------- |
       | `id`        | `STRING`      | Required. The unique [identifier for each record](/guides/get-started/concepts#record-id).                                      |
       | `values`    | `LIST<FLOAT>` | Required. A list of floating-point values that make up the [dense vector embedding](/guides/get-started/concepts#dense-vector). |
       | `metadata`  | `STRING`      | Optional. Additional [metadata](/guides/get-started/concepts#metadata) for each record. To omit from specific rows, use `NULL`. |

       <Note>
         Additional columns in the Parquet file are silently ignored during import; only `id`, `values`, and `metadata` are processed.
       </Note>

       For example:

       ```parquet theme={null}
       id | values                   | metadata
       --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
       1  | [ 3.82  2.48 -4.15 ... ] | {"year": 1984, "month": 6, "source": "source1", "title": "Example1", "text": "When ..."}
       2  | [ 1.82  3.48 -2.15 ... ] | {"year": 1990, "month": 4, "source": "source2", "title": "Example2", "text": "Who ..."}
       ```
     </Tab>

     <Tab title="Index of sparse vectors">
       To import into a namespace in an [index of sparse vectors](/guides/index-data/indexing-overview#indexes-with-sparse-vectors), the Parquet file must contain the following columns:

       | Column name     | Parquet type                                          | Description                                                                                                                                                                                     |
       | --------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
       | `id`            | `STRING`                                              | Required. The unique [identifier for each record](/guides/get-started/concepts#record-id).                                                                                                      |
       | `sparse_values` | `STRUCT<indices: LIST<UINT_32>, values: LIST<FLOAT>>` | Required. A list of floating-point values (sparse values) and a list of integer values (sparse indices) that make up the [sparse vector embedding](/guides/get-started/concepts#sparse-vector). |
       | `metadata`      | `STRING`                                              | Optional. Additional [metadata](/guides/get-started/concepts#metadata) for each record. To omit from specific rows, use `NULL`.                                                                 |

       <Note>
         Additional columns in the Parquet file are silently ignored during import; only `id`, `sparse_values`, and `metadata` are processed.
       </Note>

       For example:

       ```parquet theme={null}
       id | sparse_values                                                                                       | metadata
       --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
       1  | {"indices": [ 822745112 1009084850 1221765879 ... ], "values": [1.7958984 0.41577148 2.828125 ...]} | {"year": 1984, "month": 6, "source": "source1", "title": "Example1", "text": "When ..."}
       2  | {"indices": [ 504939989 1293001993 3201939490 ... ], "values": [1.4383747 0.72849722 1.384775 ...]} | {"year": 1990, "month": 4, "source": "source2", "title": "Example2", "text": "Who ..."}
       ```
     </Tab>

     <Tab title="Index with both dense and sparse vectors">
       To import into a namespace in an [index with both dense and sparse vectors](/guides/search/hybrid-search#use-a-single-index-for-dense-and-sparse-vectors), the Parquet file must contain the following columns:

       | Column name     | Parquet type                                          | Description                                                                                                                                                               |
       | --------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
       | `id`            | `STRING`                                              | Required. The unique [identifier for each record](/guides/get-started/concepts#record-id).                                                                                |
       | `values`        | `LIST<FLOAT>`                                         | Required. A list of floating-point values that make up the [dense vector embedding](/guides/get-started/concepts#dense-vector).                                           |
       | `sparse_values` | `STRUCT<indices: LIST<UINT_32>, values: LIST<FLOAT>>` | Optional. A list of floating-point values that make up the [sparse vector embedding](/guides/get-started/concepts#sparse-vector). To omit from specific rows, use `NULL`. |
       | `metadata`      | `STRING`                                              | Optional. Additional [metadata](/guides/get-started/concepts#metadata) for each record. To omit from specific rows, use `NULL`.                                           |

       <Note>
         Additional columns in the Parquet file are silently ignored during import; only `id`, `values`, `sparse_values`, and `metadata` are processed.
       </Note>

       For example:

       ```parquet theme={null}
       id | values                   | sparse_values                                                                          | metadata
       --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
       1  | [ 3.82  2.48 -4.15 ... ] | {"indices": [1082468256, 1009084850, 1221765879, ...], "values": [2.0, 3.0, 4.0, ...]} | {"year": 1984, "month": 6, "source": "source1", "title": "Example1", "text": "When ..."}
       2  | [ 1.82  3.48 -2.15 ... ] | {"indices": [2225824123, 1293001993, 3201939490, ...], "values": [5.0, 2.0, 3.0, ...]} | {"year": 1990, "month": 4, "source": "source2", "title": "Example2", "text": "Who ..."}
       ```
     </Tab>
   </Tabs>

3. Upload the Parquet files into the relevant subdirectory.

   For example, if you have subdirectories for the namespaces `example_namespace1` and `example_namespace2` and upload 4 Parquet files into each, your directory structure would look as follows after the upload:

   ```
   <BUCKET_OR_CONTAINER_NAME>/
   --/<IMPORT_DIR>/
   ----/example_namespace1/
   ------0.parquet
   ------1.parquet
   ------2.parquet
   ------3.parquet
   ----/example_namespace2/
   ------4.parquet
   ------5.parquet
   ------6.parquet
   ------7.parquet
   ```

## Import records into an index

<Warning>
  Review [import limits](#import-limits) before starting an import.
</Warning>

<Note>
  This guide covers importing Parquet files into indexes **without** a schema definition. Indexes with document schemas import [JSONL files](/guides/search/full-text-search#bulk-import) instead. Semantic-text (auto-embedded) fields are not yet supported in document schemas.
</Note>

Use the [`start_import`](/reference/api/latest/data-plane/start_import) operation to start an asynchronous import of vectors from object storage into an index.

* For `uri`, specify the URI of the bucket and import directory containing the namespaces and Parquet files you want to import. For example:

  * Amazon S3: `s3://BUCKET_NAME/IMPORT_DIR`
  * Google Cloud Storage: `gs://BUCKET_NAME/IMPORT_DIR`
  * Azure Blob Storage: `https://STORAGE_ACCOUNT.blob.core.windows.net/CONTAINER_NAME/IMPORT_DIR`

* For `integration_id`, specify the Integration ID of the Amazon S3, Google Cloud Storage, or Azure Blob Storage integration you created. The ID is found on the [Storage integrations](https://app.pinecone.io/organizations/-/projects/-/storage) page of the Pinecone console.

  <Note>
    An Integration ID is not needed to import from a public bucket.
  </Note>

* For `error_mode`, use `continue` or `abort`.

  * With `abort`, the operation stops if any records fail to import.
  * With `continue`, the operation continues on error, but there is not any notification about which records, if any, failed to import. To see how many records were successfully imported, use the [describe an import](#describe-an-import) operation.

<CodeGroup>
  ```python Python theme={null}
  from pinecone import Pinecone, ImportErrorMode

  pc = Pinecone(api_key="YOUR_API_KEY")

  # To get the unique host for an index, 
  # see https://docs.pinecone.io/guides/manage-data/target-an-index
  index = pc.Index(host="INDEX_HOST")
  root = "s3://example_bucket/import"

  index.start_import(
      uri=root,
      integration_id="a12b3d4c-47d2-492c-a97a-dd98c8dbefde", # Optional for public buckets
      error_mode=ImportErrorMode.CONTINUE # or ImportErrorMode.ABORT
  )
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone';

  const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' });

  // To get the unique host for an index, 
  // see https://docs.pinecone.io/guides/manage-data/target-an-index
  const index = pc.index("INDEX_NAME", "INDEX_HOST")

  const storageURI = 's3://example_bucket/import';
  const errorMode = 'continue'; // or 'abort'
  const integrationID = 'a12b3d4c-47d2-492c-a97a-dd98c8dbefde'; // Optional for public buckets

  await index.startImport(storageURI, errorMode, integrationID); 
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Pinecone;
  import io.pinecone.clients.AsyncIndex;
  import org.openapitools.db_data.client.ApiException;
  import org.openapitools.db_data.client.model.ImportErrorMode;
  import org.openapitools.db_data.client.model.StartImportResponse;

  public class StartImport {
      public static void main(String[] args) throws ApiException {
          // Initialize a Pinecone client with your API key
          Pinecone pinecone = new Pinecone.Builder("YOUR_API_KEY").build();

          // Get async imports connection object
          AsyncIndex asyncIndex = pinecone.getAsyncIndexConnection("docs-example");

          // s3 uri
          String uri = "s3://example_bucket/import";

          // Integration ID (optional for public buckets)
          String integrationId = "a12b3d4c-47d2-492c-a97a-dd98c8dbefde";

          // Start an import
          StartImportResponse response = asyncIndex.startImport(uri, integrationId, ImportErrorMode.OnErrorEnum.CONTINUE);
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "fmt"
      "log"

      "github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

      // To get the unique host for an index, 
      // see https://docs.pinecone.io/guides/manage-data/target-an-index
      idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST"})
      if err != nil {
          log.Fatalf("Failed to create IndexConnection for Host: %v", err)
  	}

      uri := "s3://example_bucket/import"
      errorMode := "continue" // or "abort"
      importRes, err := idxConnection.StartImport(ctx, uri, nil, (*pinecone.ImportErrorMode)(&errorMode))
      if err != nil {
          log.Fatalf("Failed to start import: %v", err)
      }
      fmt.Printf("Import started with ID: %s", importRes.Id)
  }
  ```

  ```bash curl theme={null}
  # To get the unique host for an index,
  # see https://docs.pinecone.io/guides/manage-data/target-an-index
  PINECONE_API_KEY="YOUR_API_KEY"
  INDEX_HOST="INDEX_HOST"

  curl "https://$INDEX_HOST/bulk/imports" \
    -H 'Api-Key: $YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -H 'X-Pinecone-Api-Version: 2025-10' \
    -d '{
          "integrationId": "a12b3d4c-47d2-492c-a97a-dd98c8dbefde",
          "uri": "s3://example_bucket/import",
          "errorMode": {
              "onError": "continue"
              }
          }'
  ```
</CodeGroup>

The response contains an `id` that you can use to [check the status of the import](#list-imports):

```json Response theme={null}
{
   "id": "101"
}
```

Once all the data is loaded, the [index builder](/guides/get-started/database-architecture#index-builder) indexes the records, which usually takes at least 10 minutes. During this indexing process, the expected job status is `InProgress`, but `100.0` percent complete. Once all the imported records are indexed and fully available for querying, the import operation is set to `Completed`. If you cancel the import before it finishes, the status changes to `Cancelled`.

<Tip>
  You can start a new import using the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/indexes). Find the index you want to import into, and click the **ellipsis (...) menu > Import data**.
</Tip>

## Track import progress

The amount of time required for an import depends on various factors, including:

* The number of records to import
* The number of namespaces to import, and the the number of records in each
* The total size (in bytes) of the import

To track an import's progress, check its status bar in the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/import) or use the [`describe_import`](/reference/api/latest/data-plane/describe_import) operation with the import ID:

<CodeGroup>
  ```python Python theme={null}
  from pinecone import Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")

  # To get the unique host for an index, 
  # see https://docs.pinecone.io/guides/manage-data/target-an-index
  index = pc.Index(host="INDEX_HOST")

  index.describe_import(id="101")
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone';

  const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' });


  // To get the unique host for an index, 
  // see https://docs.pinecone.io/guides/manage-data/target-an-index
  const index = pc.index("INDEX_NAME", "INDEX_HOST")

  const results = await index.describeImport(id='101');
  console.log(results);
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Pinecone;
  import io.pinecone.clients.AsyncIndex;
  import org.openapitools.db_data.client.ApiException;
  import org.openapitools.db_data.client.model.ImportModel;

  public class DescribeImport {
      public static void main(String[] args) throws ApiException {
          // Initialize a Pinecone client with your API key
          Pinecone pinecone = new Pinecone.Builder("YOUR_API_KEY").build();

          // Get async imports connection object
          AsyncIndex asyncIndex = pinecone.getAsyncIndexConnection("docs-example");

          // Describe import
          ImportModel importDetails = asyncIndex.describeImport("101");

          System.out.println(importDetails);
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "fmt"
      "log"

      "github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

      // To get the unique host for an index, 
      // see https://docs.pinecone.io/guides/manage-data/target-an-index
      idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST"})
      if err != nil {
          log.Fatalf("Failed to create IndexConnection for Host: %v", err)
    	}

      importID := "101"

      importDesc, err := idxConnection.DescribeImport(ctx, importID)
      if err != nil {
          log.Fatalf("Failed to describe import: %s - %v", importID, err)
      }
      fmt.Printf("Import ID: %s, Status: %s", importDesc.Id, importDesc.Status)
  }
  ```

  ```bash curl theme={null}
  # To get the unique host for an index, 
  # see https://docs.pinecone.io/guides/manage-data/target-an-index
  PINECONE_API_KEY="YOUR_API_KEY"
  INDEX_HOST="INDEX_HOST"

  curl -X GET "https://{INDEX_HOST}/bulk/imports/101" \
    -H 'Api-Key: $YOUR_API_KEY' \
    -H 'X-Pinecone-Api-Version: 2025-10'
  ```
</CodeGroup>

The response contains the import details, including the import `status`, `percent_complete`, and `records_imported`:

```json Response theme={null}
{
  "id": "101",
  "uri": "s3://example_bucket/import",
  "status": "InProgress",
  "created_at": "2024-08-19T20:49:00.754Z",
  "finished_at": "2024-08-19T20:49:00.754Z",
  "percent_complete": 42.2,
  "records_imported": 1000000
}
```

If the import fails, the response contains an `error` field with the reason for the failure. See the [Troubleshooting](#troubleshooting) section for more information.

```json Response theme={null}
{
  "id": "102",
  "uri": "s3://example_bucket/import",
  "status": "Failed",
  "percent_complete": 0.0,
  "records_imported": 0,
  "created_at": "2025-08-21T11:29:47.886797+00:00",
  "error": "User error: The namespace \"namespace1\" already exists. Imports are only allowed into nonexistent namespaces.",
  "finished_at": "2025-08-21T11:30:05.506423+00:00"
}
```

## Manage imports

### List imports

Use the [`list_imports`](/reference/api/latest/data-plane/list_imports) operation to list all of the recent and ongoing imports. By default, the operation returns up to 100 imports per page. If the `limit` parameter is passed, the operation returns up to that number of imports per page instead. For example, if `limit=3`, up to 3 imports are returned per page. Whenever there are additional imports to return, the response includes a `pagination_token` for fetching the next page of imports.

<Tabs>
  <Tab title="Python SDK">
    When using the Python SDK, `list_import` paginates automatically.

    ```python Python theme={null}
    from pinecone import Pinecone, ImportErrorMode

    pc = Pinecone(api_key="YOUR_API_KEY")

    # To get the unique host for an index, 
    # see https://docs.pinecone.io/guides/manage-data/target-an-index
    index = pc.Index(host="INDEX_HOST")

    # List using a generator that handles pagination
    for i in index.list_imports():
        print(f"id: {i.id} status: {i.status}")

    # List using a generator that fetches all results at once
    operations = list(index.list_imports())
    print(operations)
    ```

    ```json Response theme={null}
    {
      "data": [
        {
          "id": "1",
          "uri": "s3://BUCKET_NAME/PATH/TO/DIR",
          "status": "Pending",
          "started_at": "2024-08-19T20:49:00.754Z",
          "finished_at": "2024-08-19T20:49:00.754Z",
          "percent_complete": 42.2,
          "records_imported": 1000000
        }
      ],
      "pagination": {
        "next": "Tm90aGluZyB0byBzZWUgaGVyZQo="
      }
    }
    ```

    <Tip>
      You can view the list of imports for an index in the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/indexes/). Select the index and navigate to the **Imports** tab.
    </Tip>
  </Tab>

  <Tab title="Other SDKs">
    When using the Node.js SDK, Java SDK, Go SDK, or REST API to list recent and ongoing imports, you must manually fetch each page of results. To view the next page of results, include the `paginationToken` provided in the response.

    <CodeGroup>
      ```javascript JavaScript theme={null}
      import { Pinecone } from '@pinecone-database/pinecone';

      const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' });

      // To get the unique host for an index, 
      // see https://docs.pinecone.io/guides/manage-data/target-an-index
      const index = pc.index("INDEX_NAME", "INDEX_HOST")

      const results = await index.listImports({ limit: 10, paginationToken: 'Tm90aGluZyB0byBzZWUgaGVyZQo' });
      console.log(results);
      ```

      ```java Java theme={null}
      import io.pinecone.clients.Pinecone;
      import io.pinecone.clients.AsyncIndex;
      import org.openapitools.db_data.client.ApiException;
      import org.openapitools.db_data.client.model.ListImportsResponse;

      public class ListImports {
          public static void main(String[] args) throws ApiException {
              // Initialize a Pinecone client with your API key
              Pinecone pinecone = new Pinecone.Builder("YOUR_API_KEY").build();

              // Get async imports connection object
              AsyncIndex asyncIndex = pinecone.getAsyncIndexConnection("docs-example");

              // List imports
              ListImportsResponse response = asyncIndex.listImports(10, "Tm90aGluZyB0byBzZWUgaGVyZQo");

              System.out.println(response);
          }
      }
      ```

      ```go Go theme={null}
      package main

      import (
          "context"
          "fmt"
          "log"

          "github.com/pinecone-io/go-pinecone/v4/pinecone"
      )

      func main() {
          ctx := context.Background()

          pc, err := pinecone.NewClient(pinecone.NewClientParams{
              ApiKey: "YOUR_API_KEY",
          })
          if err != nil {
              log.Fatalf("Failed to create Client: %v", err)
          }

          // To get the unique host for an index, 
          // see https://docs.pinecone.io/guides/manage-data/target-an-index
          idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST"})
          if err != nil {
              log.Fatalf("Failed to create IndexConnection for Host: %v", err)
        	}

          limit := int32(10)
          firstImportPage, err := idxConnection.ListImports(ctx, &limit, nil)
          if err != nil {
              log.Fatalf("Failed to list imports: %v", err)
          }
          fmt.Printf("First page of imports: %+v", firstImportPage.Imports)

          paginationToken := firstImportPage.NextPaginationToken
          nextImportPage, err := idxConnection.ListImports(ctx, &limit, paginationToken)
          if err != nil {
              log.Fatalf("Failed to list imports: %v", err)
          }
          fmt.Printf("Second page of imports: %+v", nextImportPage.Imports)
      }
      ```

      ```bash curl theme={null}
      # To get the unique host for an index,
      # see https://docs.pinecone.io/guides/manage-data/target-an-index
      PINECONE_API_KEY="YOUR_API_KEY"
      INDEX_HOST="INDEX_HOST"

      curl -X GET "https://$INDEX_HOST/bulk/imports?paginationToken==Tm90aGluZyB0byBzZWUgaGVyZQo" \
        -H 'Api-Key: $YOUR_API_KEY' \
        -H 'X-Pinecone-Api-Version: 2025-10'
      ```
    </CodeGroup>
  </Tab>
</Tabs>

### Cancel an import

The [`cancel_import`](/reference/api/latest/data-plane/cancel_import) operation cancels an import if it is not yet finished. It has no effect if the import is already complete.

<CodeGroup>
  ```python Python theme={null}
  from pinecone import Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")

  # To get the unique host for an index, 
  # see https://docs.pinecone.io/guides/manage-data/target-an-index
  index = pc.Index(host="INDEX_HOST")

  index.cancel_import(id="101")
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone';

  const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' });

  // To get the unique host for an index, 
  // see https://docs.pinecone.io/guides/manage-data/target-an-index
  const index = pc.index("INDEX_NAME", "INDEX_HOST")

  await index.cancelImport(id='101');
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Pinecone;
  import io.pinecone.clients.AsyncIndex;
  import org.openapitools.db_data.client.ApiException;

  public class CancelImport {
      public static void main(String[] args) throws ApiException {
          // Initialize a Pinecone client with your API key
          Pinecone pinecone = new Pinecone.Builder("YOUR_API_KEY").build();

          // Get async imports connection object
          AsyncIndex asyncIndex = pinecone.getAsyncIndexConnection("docs-example");

          // Cancel import
          asyncIndex.cancelImport("2");
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "fmt"
      "log"

      "github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

      // To get the unique host for an index, 
      // see https://docs.pinecone.io/guides/manage-data/target-an-index
      idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST"})
      if err != nil {
          log.Fatalf("Failed to create IndexConnection for Host: %v", err)
    	}

      importID := "101"

      err = idxConnection.CancelImport(ctx, importID)
      if err != nil {
          log.Fatalf("Failed to cancel import: %s", importID)
      }

      importDesc, err := idxConnection.DescribeImport(ctx, importID)
      if err != nil {
          log.Fatalf("Failed to describe import: %s - %v", importID, err)
      }
  }
  ```

  ```bash curl theme={null}
  # To get the unique host for an index,
  # see https://docs.pinecone.io/guides/manage-data/target-an-index
  PINECONE_API_KEY="YOUR_API_KEY"
  INDEX_HOST="INDEX_HOST"

  curl -X DELETE "https://{INDEX_HOST}/bulk/imports/101" \
    -H 'Api-Key: $YOUR_API_KEY' \
    -H "X-Pinecone-Api-Version: 2025-10"
  ```
</CodeGroup>

```json Response theme={null}
{}
```

<Tip>
  You can cancel your import using the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/import). To cancel an ongoing import, select the index you are importing into and navigate to the **Imports** tab. Then, click the **ellipsis (...) menu > Cancel**.
</Tip>

## Import limits

<Note>
  If your import exceeds these limits, you'll get an error specifying the limit exceeded. See [Troubleshooting](/guides/index-data/import-data#troubleshooting) for details.
</Note>

| Metric                                        | Limit     |
| :-------------------------------------------- | :-------- |
| Max namespaces per import                     | 10,000    |
| Max total input data size (on-demand indexes) | 1 TB      |
| Max total input data size (DRN indexes)       | Unlimited |
| Max files per import                          | 100,000   |
| Max size per file                             | 10 GB     |

The total input data size limit does not apply to indexes with [dedicated read nodes](/guides/index-data/dedicated-read-nodes).

Bulk import supports indexes without a schema definition (Parquet files) and indexes with document schemas ([JSONL files](/guides/search/full-text-search#bulk-import)). Semantic-text (auto-embedded) fields are not yet supported in document schemas.

Also:

* You cannot import data from an AWS S3 bucket into a Pinecone index hosted on GCP or Azure.
* You cannot import data from S3 Express One Zone storage.
* You cannot import data into an existing namespace.
* When importing data into the `__default__` namespace of an index, the default namespace must be empty.
* Each import takes at least 10 minutes to complete.
* When importing into an [index with integrated embedding](/guides/index-data/indexing-overview#vector-embedding), records must contain vectors, not text. To add records with text, you must use [upsert](/guides/index-data/upsert-data).

## Troubleshooting

When an import fails, you'll see an error message with the reason for the failure in the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/import) or in the response to the [describe an import](/reference/api/latest/data-plane/describe_import) operation.

<AccordionGroup>
  <Accordion title="Namespace already exists">
    You cannot import data into an existing namespace. If your import directory structure contains a folder with the name of an existing namespace in your index, the import will fail with the following error:

    ```
    User error: The namespace "example-namespace" already exists. Imports are only allowed into nonexistent namespaces.
    ```

    To fix this, rename the folder to use a namespace name that does not yet exist.
  </Accordion>

  <Accordion title="No namespace found">
    In object storage, your directory structure must be as follows:

    ```
    example_bucket/
    --/imports/
    ----/example_namespace1/
    ------0.parquet
    ------1.parquet
    ------2.parquet
    ------3.parquet
    ----/example_namespace2/
    ------4.parquet
    ------5.parquet
    ------6.parquet
    ------7.parquet
    ```

    If a Parquet file is not nested under a namespace subdirectory, the import will fail with the following error:

    ```
    User error: \"test-import/0.parquet\": No namespace detected. Each file should be nested under a subdirectory of the URI prefix. This indicates which namespace it should be imported into.
    ```

    To fix this, move the Parquet file to a namespace subdirectory.
  </Accordion>

  <Accordion title="Parquet files not found">
    Each namespace subdirectory must contain Parquet files with data to import. If a namespace subdirectory does not include Parquet files, the import will fail with the following error:

    ```
    User error: No Parquet files found under \"gs://example_bucket/imports\". Files must be stored with the specified bucket prefix.
    ```

    To fix this, add Parquet files to the namespace subdirectory.
  </Accordion>

  <Accordion title="Invalid import URI">
    In your [start import](/reference/api/latest/data-plane/start_import) request, the import `uri` must specify only the bucket and import directory containing the namespaces and Parquet files you want to import. If the `uri` also contains a namespaces directory or a Parquet filename, the import will fail with the following error:

    ```
    User error: \"test-import/0.parquet\": It looks like you specified a complete path to a parquet file as the URI prefix to import from. Note that the URI prefix should give an ancestor directory with subdirectories to specify each namespace to import into. See https://docs.pinecone.io/guides/data/understanding-imports#directory-structure.
    ```

    To fix this, remove the namespaces directory or Parquet filename from the `uri`.
  </Accordion>

  <Accordion title="Invalid Parquet files">
    When a Parquet file is not formatted correctly, the import will fail with a message like one of the following:

    ```shell File schema errors theme={null}
    Missing required column \"{0}\"
    Unsupported column \"{0}\"
    ```

    ```shell File corruption errors theme={null}
    Parquet footer could not be parsed. Are you sure this is valid parquet?
    ```

    ```shell Type errors theme={null}
    The expected data type for column \"{column}\" is \"{expected}\", but got \"{given}\"
    The expected data type for metadata is a JSON encoded string in UTF-8 format, but got \"{given}\"
    ```

    These errors are returned for both `continue` and `abort` error modes.

    To fix these errors, check the specific error message and follow the instructions in the [Prepare your data](#prepare-your-data) section.
  </Accordion>

  <Accordion title="Invalid records">
    When the `error_mode` is `abort` and a file contains invalid records, the import will stop processing on the first invalid record and return an error message identifying the file name and row:

    ```
    User error: error reading record (file \"/0.parquet\", row 0):
    ```

    This will be followed by an error message identifying the specific issue. For example:

    ```shell Missing values theme={null}
    missing required values in column \"{column}\"
    ```

    ```shell Invalid metadata  theme={null}
    Failed to parse metadata: {msg}
    ```

    ```shell Invalid vectors theme={null}
    Upserting dense vectors is not supported for indexes that store only sparse vectors
    ```

    When the `error_mode` is `continue`, the import will skip individual invalid records. However, if all records are invalid and skipped (for example, the vector type in the file does not match the vector type of the index), the import will fail with a general message:

    ```
    User error: No vectors added, all rows were skipped for namespace: example-namespace
    ```

    To fix these errors, check the specific error message and follow the instructions in the [Prepare your data](#prepare-your-data) section.
  </Accordion>

  <Accordion title="Duplicate records">
    When your import contains duplicate vectors (records with identical vector values), the duplicates are marked as skipped and not imported. Only one occurrence of each unique vector is added to the index.

    This applies to both `continue` and `abort` error modes:

    * With `abort`: The import fails when it encounters a duplicate vector within the import.
    * With `continue`: The import proceeds, skipping duplicate records silently.

    **Example scenario:**
    If your Parquet file contains:

    ```parquet theme={null}
    id | values
    ---|---------
    1  | [0.1, 0.2, 0.3]
    2  | [0.1, 0.2, 0.3]  ← Duplicate of record 1, will be skipped
    3  | [0.4, 0.5, 0.6]
    ```

    Only records 1 and 3 will be imported.

    To prevent this from happening, deduplicate your source data before creating Parquet files by removing records with identical vector values.
  </Accordion>

  <Accordion title="Import exceeds maximum data size for on-demand">
    On-demand indexes have a maximum total input data size of 1 TB per import. If your import exceeds this limit, it will fail with the following error:

    ```
    Import ({size} GB) exceeds the maximum input data size of 1000 GB for on-demand. Consider using Dedicated Read Nodes (DRN) for larger index sizes, or contact support for your use-case.
    ```

    To fix this, either reduce the total size of your import to under 1 TB, use an index with [dedicated read nodes](/guides/index-data/dedicated-read-nodes) (which have no total data size limit for imports), or [contact support](https://app.pinecone.io/organizations/-/settings/support/ticket).
  </Accordion>
</AccordionGroup>

## See also

* [Integrate with Amazon S3](/guides/operations/integrations/integrate-with-amazon-s3)
* [Integrate with Google Cloud Storage](/guides/operations/integrations/integrate-with-google-cloud-storage)
* [Integrate with Azure Blob Storage](/guides/operations/integrations/integrate-with-azure-blob-storage)
* [Pinecone's pricing](https://www.pinecone.io/pricing/)


# Indexing overview
Source: https://docs.pinecone.io/guides/index-data/indexing-overview

Learn how indexing works in Pinecone: serverless indexes, document schemas, namespaces, integrated embedding, and metadata filtering.

## Indexes

In Pinecone, you store data in indexes. A serverless index holds your data as [documents](/guides/get-started/concepts#document) or [records](/guides/get-started/concepts#record), depending on how the index was created: an index created with a document schema holds documents, while an index created with a dense or sparse vector type holds records. A single index with a document schema can mix multiple ranking field types: a `dense_vector` field for [semantic search](/guides/search/semantic-search), a `sparse_vector` field for [sparse-vector retrieval](/guides/search/lexical-search), and one or more `string` fields with `full_text_search` enabled for [full-text search](/guides/search/full-text-search) with BM25 and Lucene queries. Any other fields you upsert are stored as metadata, automatically indexed for filtering — no schema declaration required.

One index per use case is the typical pattern. Because a document can combine vectors, text, and metadata in the same record, a single index often covers what previously required two — pick the ranking signal per query with `score_by`.

### Full-text search

Full-text search is **BM25 token matching with Lucene query syntax** over text fields in your schema — `string` fields you've declared with `full_text_search` enabled. No model required — Pinecone handles tokenization, IDF, and length normalization at index time and BM25 scoring at query time.

When you search, you rank results via `score_by`: `text` (BM25), `query_string` (Lucene), `dense_vector`, or `sparse_vector`. All scoring methods can be combined with metadata filters, including the text match operators (`$match_phrase`, `$match_all`, `$match_any`) for phrase and token matching. For example:

```json theme={null}
{
  "score_by": [{ "type": "text", "field": "body", "query": "machine learning" }],
  "top_k": 10
}
```

Reach for full-text search when relevance comes down to specific tokens appearing in both the query and the data: SKUs, error messages, code, named entities. For semantic similarity over natural-language queries, see [Indexes with dense vectors](#indexes-with-dense-vectors); for retrieval with a learned sparse encoder, see [Indexes with sparse vectors](#indexes-with-sparse-vectors).

Learn more:

* [Full-text search guide](/guides/search/full-text-search)
* [Schema definition](/guides/search/full-text-search#schema-definition)
* [Upsert documents](/guides/search/full-text-search#upsert-documents)

### Indexes with dense vectors

A dense vector encodes the meaning of text, images, or other data as a fixed-length list of numbers. Items with similar meaning sit close to each other in vector space, and a query returns the records closest to the query vector. This is **semantic search** (also called nearest neighbor search, similarity search, or vector search).

For the underlying concept, see [Dense vector](/guides/get-started/concepts#dense-vector).

Learn more:

* [Create an index for dense vectors](/guides/index-data/create-an-index#create-an-index-for-dense-vectors)
* [Upsert dense vectors](/guides/index-data/upsert-data#upsert-dense-vectors)
* [Semantic search](/guides/search/semantic-search)

### Indexes with sparse vectors

A sparse vector represents tokens (or token-like features) and their weights, with the vast majority of dimensions zero. A query returns records that share the most weighted tokens with the query vector — **sparse-vector lexical search**.

Sparse vectors come from a sparse embedding model. Pinecone hosts [`pinecone-sparse-english-v0`](/models/pinecone-sparse-english-v0); you can also bring your own. For the underlying concept and the distinction from full-text search, see [Index with sparse vectors](/guides/get-started/concepts#index-with-sparse-vectors).

Learn more:

* [Create an index for sparse vectors](/guides/index-data/create-an-index#create-an-index-for-sparse-vectors)
* [Upsert sparse vectors](/guides/index-data/upsert-data#upsert-sparse-vectors)
* [Lexical search](/guides/search/lexical-search)

#### Limitations

Indexes of sparse vectors have the following limitations:

* Max non-zero values per sparse vector: 1000
* Max upserts per second per index of sparse vectors: 10
* Max queries per second per index of sparse vectors: 100
* Max `top_k` value per query: 1000

  <Note>
    You may get fewer than `top_k` results if `top_k` is larger than the number of sparse vectors in your index that match your query. That is, any vectors where the dotproduct score is `0` will be discarded.
  </Note>
* Max query results size: 4MB

<Tip>
  Semantic search can miss exact keyword matches, while lexical search can miss semantically related results. To get the best of both, use [hybrid search](/guides/search/hybrid-search) — combine a lexical signal (BM25 or sparse) with a dense signal at query time, often with reranking.
</Tip>

## Namespaces

Within an index, records are partitioned into namespaces, and all [upserts](/guides/index-data/upsert-data), [queries](/guides/search/search-overview), and other data read and write operations always target one namespace. This has two main benefits:

* **Multitenancy:** When you need to isolate data between customers, you can use one namespace per customer and target each customer's writes and queries to their dedicated namespace. See [Implement multitenancy](/guides/index-data/implement-multitenancy) for end-to-end guidance.

* **Faster queries:** When you divide records into namespaces in a logical way, you speed up queries by ensuring only relevant records are scanned. The same applies to fetching records, listing record IDs, and other data operations.

Namespaces are created automatically during [upsert](/guides/index-data/upsert-data). If a namespace doesn't exist, it is created implicitly.

<Note>
  [Namespaces per serverless index](/reference/api/database-limits#namespaces-per-serverless-index) vary by plan. On the Standard and Enterprise plans, Pinecone can accommodate million-scale namespaces and beyond for specific use cases. If your application requires more than 100,000 namespaces, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).
</Note>

<img />

<img />

## Vector embedding

[Dense vectors](/guides/get-started/concepts#dense-vector) and [sparse vectors](/guides/get-started/concepts#sparse-vector) are the basic units of data in Pinecone and what Pinecone was specially designed to store and work with. Dense vectors represents the semantics of data such as text, images, and audio recordings, while sparse vectors represent documents or queries in a way that captures keyword information.

To transform data into vector format, you use an embedding model. You can either use Pinecone's integrated embedding models to convert your source data to vectors automatically, or you can use an external embedding model and bring your own vectors to Pinecone.

### Integrated embedding

1. [Create an index](/guides/index-data/create-an-index) that is integrated with one of Pinecone's [hosted embedding models](/guides/index-data/create-an-index#embedding-models).
2. [Upsert](/guides/index-data/upsert-data) your source text. Pinecone uses the integrated model to convert the text to vectors automatically.
3. [Search](/guides/search/search-overview) with a query text. Again, Pinecone uses the integrated model to convert the text to a vector automatically.

<Note>
  Indexes with integrated embedding do not support [updating](/guides/manage-data/update-data) or [importing](/guides/index-data/import-data) with text.
</Note>

### Bring your own vectors

1. Use an embedding model to convert your text to vectors. The model can be [hosted by Pinecone](/reference/api/latest/inference/generate-embeddings) or an external provider.
2. [Create an index](/guides/index-data/create-an-index) that matches the characteristics of the model.
3. [Upsert](/guides/index-data/upsert-data) your vectors directly.
4. Use the same external embedding model to convert a query to a vector.
5. [Search](/guides/search/search-overview) with your query vector directly.

## Data ingestion

<Tip>
  To control costs when ingesting large datasets (10,000,000+ records), use [import](/guides/index-data/import-data) instead of upsert.
</Tip>

There are two ways to ingest data into an index:

* [Importing from object storage](/guides/index-data/import-data) is the most efficient and cost-effective way to load large numbers of records into an index. You store your data as Parquet files in object storage, integrate your object storage with Pinecone, and then start an asynchronous, long-running operation that imports and indexes your records.

* [Upserting](/guides/index-data/upsert-data) is intended for ongoing writes to an index. [Batch upserting](/guides/index-data/upsert-data#upsert-in-batches) can improve throughput performance and is a good option for larger numbers of records (up to 1000 per batch) if you cannot work around import's current limitations.

## Metadata

Every [record](/guides/get-started/concepts#record) in an index must contain an ID and a vector. In addition, you can include metadata key-value pairs to store additional information or context. When you query the index, you can then include a [metadata filter](/guides/search/filter-by-metadata) to limit the search to records matching a filter expression. Searches without metadata filters do not consider metadata and search the entire namespace.

### Metadata format

* Metadata fields must be key-value pairs in a flat JSON object. Nested JSON objects are not supported.
* Keys must be strings and must not start with a `$`.
* Values must be one of the following data types:
  * String
  * Integer (converted to a 64-bit floating point by Pinecone)
  * Floating point
  * Boolean (`true`, `false`)
  * List of strings
* Null metadata values aren't supported. Instead of setting a key to `null`, remove the key from the metadata payload.

**Examples**

<CodeGroup>
  ```json Valid metadata theme={null}
  {
    "document_id": "document1",
    "document_title": "Introduction to Vector Databases",
    "chunk_number": 1,
    "chunk_text": "First chunk of the document content...",
    "is_public": true,
    "tags": ["beginner", "database", "vector-db"],
    "scores": ["85", "92"]
  }
  ```

  ```json Invalid metadata theme={null}
  {
    "document": {       // Nested JSON objects are not supported
      "document_id": "document1",
      "document_title": "Introduction to Vector Databases",
    },
    "$chunk_number": 1, // Keys must not start with a `$`
    "chunk_text": null, // Null values are not supported
    "is_public": true,
    "tags": ["beginner", "database", "vector-db"],
    "scores": [85, 92]  // Lists of non-strings are not supported
  }
  ```
</CodeGroup>

### Metadata size

Pinecone supports 40KB of metadata per record.

### Metadata filter expressions

Pinecone's filtering language supports the following operators:

| Operator  | Function                                                                                                                   | Supported types         |
| :-------- | :------------------------------------------------------------------------------------------------------------------------- | :---------------------- |
| `$eq`     | Matches  with metadata values that are equal to a specified value. Example: `{"genre": {"$eq": "documentary"}}`            | Number, string, boolean |
| `$ne`     | Matches  with metadata values that are not equal to a specified value. Example: `{"genre": {"$ne": "drama"}}`              | Number, string, boolean |
| `$gt`     | Matches  with metadata values that are greater than a specified value. Example: `{"year": {"$gt": 2019}}`                  | Number                  |
| `$gte`    | Matches  with metadata values that are greater than or equal to a specified value. Example:`{"year": {"$gte": 2020}}`      | Number                  |
| `$lt`     | Matches  with metadata values that are less than a specified value. Example: `{"year": {"$lt": 2020}}`                     | Number                  |
| `$lte`    | Matches  with metadata values that are less than or equal to a specified value. Example: `{"year": {"$lte": 2020}}`        | Number                  |
| `$in`     | Matches  with metadata values that are in a specified array. Example: `{"genre": {"$in": ["comedy", "documentary"]}}`      | String, number          |
| `$nin`    | Matches  with metadata values that are not in a specified array. Example: `{"genre": {"$nin": ["comedy", "documentary"]}}` | String, number          |
| `$exists` | Matches  with the specified metadata field. Example: `{"genre": {"$exists": true}}`                                        | Number, string, boolean |
| `$and`    | Joins query clauses with a logical `AND`. Example: `{"$and": [{"genre": {"$eq": "drama"}}, {"year": {"$gte": 2020}}]}`     | -                       |
| `$or`     | Joins query clauses with a logical `OR`. Example: `{"$or": [{"genre": {"$eq": "drama"}}, {"year": {"$gte": 2020}}]}`       | -                       |

<Note>
  Only `$and` and `$or` are allowed at the top level of the query expression.
</Note>

<Note>
  Each `$in` or `$nin` operator accepts a maximum of 10,000 values. Exceeding this limit will cause the request to fail. For more information, see [Metadata filter limits](/reference/api/database-limits#metadata-filter-limits).
</Note>

For example, the following has a `"genre"` metadata field with a list of strings:

```JSON JSON theme={null}
{ "genre": ["comedy", "documentary"] }
```

This means `"genre"` takes on both values, and requests with the following filters will match:

```JSON JSON theme={null}
{"genre":"comedy"}

{"genre": {"$in":["documentary","action"]}}

{"$and": [{"genre": "comedy"}, {"genre":"documentary"}]}
```

However, requests with the following filter will **not** match:

```JSON JSON theme={null}
{ "$and": [{ "genre": "comedy" }, { "genre": "drama" }] }
```

Additionally, requests with the following filters will **not** match because they are invalid. They will result in a compilation error:

```json JSON theme={null}
# INVALID QUERY:
{"genre": ["comedy", "documentary"]}
```

```json JSON theme={null}
# INVALID QUERY:
{"genre": {"$eq": ["comedy", "documentary"]}}
```


# Upsert records
Source: https://docs.pinecone.io/guides/index-data/upsert-data

Upsert dense, sparse, and text records into Pinecone indexes, batch upserts for higher throughput, and partition data with namespaces.

This page shows you how to upsert records into a namespace in an index. [Namespaces](/guides/index-data/indexing-overview#namespaces) let you partition records within an index and are essential for [implementing multitenancy](/guides/index-data/implement-multitenancy) when you need to isolate the data of each customer/user.

If a record ID already exists, upserting overwrites the entire record. To change only part of a record, [update ](/guides/manage-data/update-data) the record.

<Tip>
  Upserts consume [write units (WUs)](/guides/manage-cost/understanding-cost#write-units). See [Understanding cost](/guides/manage-cost/understanding-cost#upsert) for how upsert cost is calculated.
</Tip>

<Tip>
  To control costs when ingesting large datasets (10,000,000+ records), use [import](/guides/index-data/import-data) instead of upsert.
</Tip>

## Upsert dense vectors

<Tabs>
  <Tab title="Upsert text">
    <Note>
      Upserting text is supported only for [indexes with integrated embedding](/guides/index-data/indexing-overview#integrated-embedding).
    </Note>

    To upsert source text into an [index of dense vectors with integrated embedding](/guides/index-data/create-an-index#create-an-index-for-dense-vectors), use the [`upsert_records`](/reference/api/latest/data-plane/upsert_records) operation. Pinecone converts the text to dense vectors automatically using the hosted dense embedding model associated with the index.

    * Specify the [`namespace`](/guides/index-data/indexing-overview#namespaces) to upsert into. If the namespace doesn't exist, it is created. To use the default namespace, set the namespace to `"__default__"`.
    * Format your input data as records, each with the following:
      * An `_id` field with a unique record identifier for the index namespace. `id` can be used as an alias for `_id`.
      * A field with the source text to convert to a vector. This field must match the `field_map` specified in the index.
      * Additional fields are stored as record [metadata](/guides/index-data/indexing-overview#metadata) and can be returned in search results or used to [filter search results](/guides/search/filter-by-metadata).

    For example, the following code converts the sentences in the `chunk_text` fields to dense vectors and then upserts them into `example-namespace` in an example index. The additional `category` field is stored as metadata.

    <CodeGroup>
      ```python Python theme={null}
      from pinecone import Pinecone

      pc = Pinecone(api_key="YOUR_API_KEY")

      # To get the unique host for an index, 
      # see https://docs.pinecone.io/guides/manage-data/target-an-index
      index = pc.Index(host="INDEX_HOST")

      # Upsert records into a namespace
      # `chunk_text` fields are converted to dense vectors
      # `category` fields are stored as metadata
      index.upsert_records(
          "example-namespace",
          [
              {
                  "_id": "rec1",
                  "chunk_text": "Apples are a great source of dietary fiber, which supports digestion and helps maintain a healthy gut.",
                  "category": "digestive system", 
              },
              {
                  "_id": "rec2",
                  "chunk_text": "Apples originated in Central Asia and have been cultivated for thousands of years, with over 7,500 varieties available today.",
                  "category": "cultivation",
              },
              {
                  "_id": "rec3",
                  "chunk_text": "Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases.",
                  "category": "immune system",
              },
              {
                  "_id": "rec4",
                  "chunk_text": "The high fiber content in apples can also help regulate blood sugar levels, making them a favorable snack for people with diabetes.",
                  "category": "endocrine system",
              },
          ]
      ) 
      ```

      ```javascript JavaScript theme={null}
      import { Pinecone } from '@pinecone-database/pinecone'

      const pc = new Pinecone({ apiKey: "YOUR_API_KEY" })

      // To get the unique host for an index, 
      // see https://docs.pinecone.io/guides/manage-data/target-an-index
      const namespace = pc.index("INDEX_NAME", "INDEX_HOST").namespace("example-namespace");

      // Upsert records into a namespace
      // `chunk_text` fields are converted to dense vectors
      // `category` is stored as metadata
      await namespace.upsertRecords([
              {
                  "_id": "rec1",
                  "chunk_text": "Apples are a great source of dietary fiber, which supports digestion and helps maintain a healthy gut.",
                  "category": "digestive system", 
              },
              {
                  "_id": "rec2",
                  "chunk_text": "Apples originated in Central Asia and have been cultivated for thousands of years, with over 7,500 varieties available today.",
                  "category": "cultivation",
              },
              {
                  "_id": "rec3",
                  "chunk_text": "Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases.",
                  "category": "immune system",
              },
              {
                  "_id": "rec4",
                  "chunk_text": "The high fiber content in apples can also help regulate blood sugar levels, making them a favorable snack for people with diabetes.",
                  "category": "endocrine system",
              }
      ]);
      ```

      ```java Java theme={null}
      import io.pinecone.clients.Index;
      import io.pinecone.configs.PineconeConfig;
      import io.pinecone.configs.PineconeConnection;
      import org.openapitools.db_data.client.ApiException;

      import java.util.*;

      public class UpsertText {
          public static void main(String[] args) throws ApiException {
              PineconeConfig config = new PineconeConfig("YOUR_API_KEY");
              config.setHost("INDEX_HOST");
              PineconeConnection connection = new PineconeConnection(config);

              Index index = new Index(config, connection, "integrated-dense-java");
              ArrayList<Map<String, String>> upsertRecords = new ArrayList<>();

              HashMap<String, String> record1 = new HashMap<>();
              record1.put("_id", "rec1");
              record1.put("category", "digestive system");
              record1.put("chunk_text", "Apples are a great source of dietary fiber, which supports digestion and helps maintain a healthy gut.");

              HashMap<String, String> record2 = new HashMap<>();
              record2.put("_id", "rec2");
              record2.put("category", "cultivation");
              record2.put("chunk_text", "Apples originated in Central Asia and have been cultivated for thousands of years, with over 7,500 varieties available today.");

              HashMap<String, String> record3 = new HashMap<>();
              record3.put("_id", "rec3");
              record3.put("category", "immune system");
              record3.put("chunk_text", "Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases.");

              HashMap<String, String> record4 = new HashMap<>();
              record4.put("_id", "rec4");
              record4.put("category", "endocrine system");
              record4.put("chunk_text", "The high fiber content in apples can also help regulate blood sugar levels, making them a favorable snack for people with diabetes.");

              upsertRecords.add(record1);
              upsertRecords.add(record2);
              upsertRecords.add(record3);
              upsertRecords.add(record4);

              index.upsertRecords("example-namespace", upsertRecords);
          }
      }
      ```

      ```go Go theme={null}
      package main

      import (
          "context"
          "fmt"
          "log"

          "github.com/pinecone-io/go-pinecone/v4/pinecone"
      )

      func main() {
          ctx := context.Background()

          pc, err := pinecone.NewClient(pinecone.NewClientParams{
              ApiKey: "YOUR_API_KEY",
          })
          if err != nil {
              log.Fatalf("Failed to create Client: %v", err)
          }

          // To get the unique host for an index, 
          // see https://docs.pinecone.io/guides/manage-data/target-an-index
          idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST", Namespace: "example-namespace"})
          if err != nil {
              log.Fatalf("Failed to create IndexConnection for Host: %v", err)
      	  }

          // Upsert records into a namespace
          // `chunk_text` fields are converted to dense vectors
          // `category` is stored as metadata
      	records := []*pinecone.IntegratedRecord{
              {
                  "_id": "rec1",
                  "chunk_text": "Apples are a great source of dietary fiber, which supports digestion and helps maintain a healthy gut.",
                  "category": "digestive system", 
              },
              {
                  "_id": "rec2",
                  "chunk_text": "Apples originated in Central Asia and have been cultivated for thousands of years, with over 7,500 varieties available today.",
                  "category": "cultivation",
              },
              {
                  "_id": "rec3",
                  "chunk_text": "Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases.",
                  "category": "immune system",
              },
              {
                  "_id": "rec4",
                  "chunk_text": "The high fiber content in apples can also help regulate blood sugar levels, making them a favorable snack for people with diabetes.",
                  "category": "endocrine system",
              },
      	}

      	err = idxConnection.UpsertRecords(ctx, records)
      	if err != nil {
      		log.Fatalf("Failed to upsert vectors: %v", err)
      	}
      }
      ```

      ```shell curl theme={null}
      # To get the unique host for an index,
      # see https://docs.pinecone.io/guides/manage-data/target-an-index
      INDEX_HOST="INDEX_HOST"
      NAMESPACE="YOUR_NAMESPACE"
      PINECONE_API_KEY="YOUR_API_KEY"

      # Upsert records into a namespace
      # `chunk_text` fields are converted to dense vectors
      # `category` is stored as metadata
      curl "https://$INDEX_HOST/records/namespaces/$NAMESPACE/upsert" \
        -H "Content-Type: application/x-ndjson" \
        -H "Api-Key: $PINECONE_API_KEY" \
        -H "X-Pinecone-Api-Version: 2025-10" \
        -d '{"_id": "rec1", "chunk_text": "Apples are a great source of dietary fiber, which supports digestion and helps maintain a healthy gut.", "category": "digestive system"}
            {"_id": "rec2", "chunk_text": "Apples originated in Central Asia and have been cultivated for thousands of years, with over 7,500 varieties available today.", "category": "cultivation"}
            {"_id": "rec3", "chunk_text": "Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases.", "category": "immune system"}
            {"_id": "rec4", "chunk_text": "The high fiber content in apples can also help regulate blood sugar levels, making them a favorable snack for people with diabetes.", "category": "endocrine system"}'
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Upsert vectors">
    To upsert dense vectors into an [index of dense vectors](/guides/index-data/create-an-index#create-an-index-for-dense-vectors), use the [`upsert`](/reference/api/latest/data-plane/upsert) operation as follows:

    * Specify the [`namespace`](/guides/index-data/indexing-overview#namespaces) to upsert into. If the namespace doesn't exist, it is created. To use the default namespace, set the namespace to `"__default__"`.
    * Format your input data as records, each with the following:
      * An `id` field with a unique record identifier for the index namespace.
      * A `values` field with the dense vector values.
      * Optionally, a `metadata` field with [key-value pairs](/guides/index-data/indexing-overview#metadata) to store additional information or context. When you query the index, you can use metadata to [filter search results](/guides/search/filter-by-metadata).

    <CodeGroup>
      ```Python Python theme={null}
      from pinecone.grpc import PineconeGRPC as Pinecone

      pc = Pinecone(api_key="YOUR_API_KEY")

      # To get the unique host for an index, 
      # see https://docs.pinecone.io/guides/manage-data/target-an-index
      index = pc.Index(host="INDEX_HOST")

      index.upsert(
        vectors=[
          {
            "id": "A", 
            "values": [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1], 
            "metadata": {"genre": "comedy", "year": 2020}
          },
          {
            "id": "B", 
            "values": [0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2],
            "metadata": {"genre": "documentary", "year": 2019}
          },
          {
            "id": "C", 
            "values": [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3],
            "metadata": {"genre": "comedy", "year": 2019}
          },
          {
            "id": "D", 
            "values": [0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4],
            "metadata": {"genre": "drama"}
          }
        ],
        namespace="example-namespace"
      )
      ```

      ```javascript JavaScript theme={null}
      import { Pinecone } from '@pinecone-database/pinecone'

      const pc = new Pinecone({ apiKey: "YOUR_API_KEY" })

      // To get the unique host for an index, 
      // see https://docs.pinecone.io/guides/manage-data/target-an-index
      const index = pc.index("INDEX_NAME", "INDEX_HOST")

      const records = [
          {
            id: 'A',
            values: [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1],
            metadata: { genre: "comedy", year: 2020 },
          },
          {
            id: 'B',
            values: [0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2],
            metadata: { genre: "documentary", year: 2019 },
          },
          {
            id: 'C',
            values: [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3],
            metadata: { genre: "comedy", year: 2019 },
          },
          {
            id: 'D',
            values: [0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4],
            metadata: { genre: "drama" },
          }
      ]

      await index.namespace('example-namespace').upsert({ records: records });
      ```

      ```java Java theme={null}
      import com.google.protobuf.Struct;
      import com.google.protobuf.Value;
      import io.pinecone.clients.Index;
      import io.pinecone.configs.PineconeConfig;
      import io.pinecone.configs.PineconeConnection;

      import java.util.Arrays;
      import java.util.List;

      public class UpsertExample {
          public static void main(String[] args) {
              PineconeConfig config = new PineconeConfig("YOUR_API_KEY");
              // To get the unique host for an index, 
              // see https://docs.pinecone.io/guides/manage-data/target-an-index
              config.setHost("INDEX_HOST");
              PineconeConnection connection = new PineconeConnection(config);
              Index index = new Index(connection, "INDEX_NAME");
              List<Float> values1 = Arrays.asList(0.1f, 0.1f, 0.1f, 0.1f, 0.1f, 0.1f, 0.1f, 0.1f);
              List<Float> values2 = Arrays.asList(0.2f, 0.2f, 0.2f, 0.2f, 0.2f, 0.2f, 0.2f, 0.2f);
              List<Float> values3 = Arrays.asList(0.3f, 0.3f, 0.3f, 0.3f, 0.3f, 0.3f, 0.3f, 0.3f);
              List<Float> values4 = Arrays.asList(0.4f, 0.4f, 0.4f, 0.4f, 0.4f, 0.4f, 0.4f, 0.4f);
              Struct metaData1 = Struct.newBuilder()
                      .putFields("genre", Value.newBuilder().setStringValue("comedy").build())
                      .putFields("year", Value.newBuilder().setNumberValue(2020).build())
                      .build();
              Struct metaData2 = Struct.newBuilder()
                      .putFields("genre", Value.newBuilder().setStringValue("documentary").build())
                      .putFields("year", Value.newBuilder().setNumberValue(2019).build())
                      .build();
              Struct metaData3 = Struct.newBuilder()
                      .putFields("genre", Value.newBuilder().setStringValue("comedy").build())
                      .putFields("year", Value.newBuilder().setNumberValue(2019).build())
                      .build();
              Struct metaData4 = Struct.newBuilder()
                      .putFields("genre", Value.newBuilder().setStringValue("drama").build())
                      .build();

              index.upsert("A", values1, null, null, metaData1, 'example-namespace');
              index.upsert("B", values2, null, null, metaData2, 'example-namespace');
              index.upsert("C", values3, null, null, metaData3, 'example-namespace');
              index.upsert("D", values4, null, null, metaData4, 'example-namespace');
          }
      }
      ```

      ```go Go theme={null}
      package main

      import (
          "context"
          "fmt"
          "log"

          "github.com/pinecone-io/go-pinecone/v4/pinecone"
          "google.golang.org/protobuf/types/known/structpb"
      )

      func main() {
          ctx := context.Background()

          pc, err := pinecone.NewClient(pinecone.NewClientParams{
              ApiKey: "YOUR_API_KEY",
          })
          if err != nil {
              log.Fatalf("Failed to create Client: %v", err)
          }

          // To get the unique host for an index, 
          // see https://docs.pinecone.io/guides/manage-data/target-an-index
          idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST", Namespace: "example-namespace"})
          if err != nil {
              log.Fatalf("Failed to create IndexConnection for Host: %v", err)
      	  }

          metadataMap1 := map[string]interface{}{
              "genre": "comedy",
              "year": 2020,
          }

          metadata1, err := structpb.NewStruct(metadataMap1)
          if err != nil {
              log.Fatalf("Failed to create metadata map: %v", err)
          }

          metadataMap2 := map[string]interface{}{
              "genre": "documentary",
              "year": 2019,
          }

          metadata2, err := structpb.NewStruct(metadataMap2)
          if err != nil {
              log.Fatalf("Failed to create metadata map: %v", err)
          }

          metadataMap3 := map[string]interface{}{
              "genre": "comedy",
              "year": 2019,
          }

          metadata3, err := structpb.NewStruct(metadataMap3)
          if err != nil {
              log.Fatalf("Failed to create metadata map: %v", err)
          }

          metadataMap4 := map[string]interface{}{
              "genre": "drama",
          }

          metadata4, err := structpb.NewStruct(metadataMap4)
          if err != nil {
              log.Fatalf("Failed to create metadata map: %v", err)
          }

          vectors := []*pinecone.Vector{
              {
                  Id:     "A",
                  Values: []float32{0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1},
                  Metadata: metadata1,
              },
              {
                  Id:     "B",
                  Values: []float32{0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2},
                  Metadata: metadata2,
              },
              {
                  Id:     "C",
                  Values: []float32{0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3},
                  Metadata: metadata3,
              },   
              {
                  Id:     "D",
                  Values: []float32{0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4},
                  Metadata: metadata4,
              },   
          }

          count, err := idxConnection.UpsertVectors(ctx, vectors)
          if err != nil {
              log.Fatalf("Failed to upsert vectors: %v", err)
          } else {
              fmt.Printf("Successfully upserted %d vector(s)!\n", count)
          }
      }
      ```

      ```bash curl theme={null}
      # To get the unique host for an index,
      # see https://docs.pinecone.io/guides/manage-data/target-an-index
      PINECONE_API_KEY="YOUR_API_KEY"
      INDEX_HOST="INDEX_HOST"

      curl "https://$INDEX_HOST/vectors/upsert" \
        -H "Api-Key: $PINECONE_API_KEY" \
        -H 'Content-Type: application/json' \
        -H "X-Pinecone-Api-Version: 2025-10" \
        -d '{
          "vectors": [
            {
              "id": "A",
              "values": [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1],
              "metadata": {"genre": "comedy", "year": 2020}
            },
            {
              "id": "B",
              "values": [0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2],
              "metadata": {"genre": "documentary", "year": 2019}
            },
            {
              "id": "C",
              "values": [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3],
              "metadata": {"genre": "comedy", "year": 2019}
            },
            {
              "id": "D",
              "values": [0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4],
              "metadata": {"genre": "drama"}
            }
          ],
          "namespace": "example-namespace"
        }'
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Upsert sparse vectors

<Note>
  Sparse-vector upsert is the right choice when your data is encoded by a learned sparse model (for example, [`pinecone-sparse-english-v0`](/models/pinecone-sparse-english-v0)) or when your application owns the sparse-vector representation directly. For BM25-style keyword search over raw text with no model to manage, see [Upsert documents](#upsert-documents).
</Note>

<Tabs>
  <Tab title="Upsert text">
    <Note>
      Upserting text is supported only for [indexes with integrated embedding](/guides/index-data/indexing-overview#integrated-embedding).
    </Note>

    To upsert source text into an [index of sparse vectors with integrated embedding](/guides/index-data/create-an-index#create-an-index-for-sparse-vectors), use the [`upsert_records`](/reference/api/latest/data-plane/upsert_records) operation. Pinecone converts the text to sparse vectors automatically using the hosted sparse embedding model associated with the index.

    * Specify the [`namespace`](/guides/index-data/indexing-overview#namespaces) to upsert into. If the namespace doesn't exist, it is created. To use the default namespace, set the namespace to `"__default__"`.
    * Format your input data as records, each with the following:
      * An `_id` field with a unique record identifier for the index namespace. `id` can be used as an alias for `_id`.
      * A field with the source text to convert to a vector. This field must match the `field_map` specified in the index.
      * Additional fields are stored as record [metadata](/guides/index-data/indexing-overview#metadata) and can be returned in search results or used to [filter search results](/guides/search/filter-by-metadata).

    For example, the following code converts the sentences in the `chunk_text` fields to sparse vectors and then upserts them into `example-namespace` in an example index. The additional `category` and `quarter` fields are stored as metadata.

    <CodeGroup>
      ```python Python theme={null}
      from pinecone import Pinecone

      pc = Pinecone(api_key="YOUR_API_KEY")

      # To get the unique host for an index, 
      # see https://docs.pinecone.io/guides/manage-data/target-an-index
      index = pc.Index(host="INDEX_HOST")

      # Upsert records into a namespace
      # `chunk_text` fields are converted to sparse vectors
      # `category` and `quarter` fields are stored as metadata
      index.upsert_records(
          "example-namespace",
          [
              { 
                  "_id": "vec1", 
                  "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.", 
                  "category": "technology",
                  "quarter": "Q3"
              },
              { 
                  "_id": "vec2", 
                  "chunk_text": "Analysts suggest that AAPL'\''s upcoming Q4 product launch event might solidify its position in the premium smartphone market.", 
                  "category": "technology",
                  "quarter": "Q4"
              },
              { 
                  "_id": "vec3", 
                  "chunk_text": "AAPL'\''s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production.",
                  "category": "technology",
                  "quarter": "Q3"
              },
              { 
                  "_id": "vec4", 
                  "chunk_text": "AAPL may consider healthcare integrations in Q4 to compete with tech rivals entering the consumer wellness space.", 
                  "category": "technology",
                  "quarter": "Q4"
              }
          ]
      )

      time.sleep(10) # Wait for the upserted vectors to be indexed
      ```

      ```javascript JavaScript theme={null}
      import { Pinecone } from '@pinecone-database/pinecone'

      const pc = new Pinecone({ apiKey: "YOUR_API_KEY" })

      // To get the unique host for an index, 
      // see https://docs.pinecone.io/guides/manage-data/target-an-index
      const namespace = pc.index("INDEX_NAME", "INDEX_HOST").namespace("example-namespace");

      // Upsert records into a namespace
      // `chunk_text` fields are converted to sparse vectors
      // `category` and `quarter` fields are stored as metadata
      await namespace.upsertRecords([
          { 
              "_id": "vec1", 
              "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.", 
              "category": "technology",
              "quarter": "Q3"
          },
          { 
              "_id": "vec2", 
              "chunk_text": "Analysts suggest that AAPL'\''s upcoming Q4 product launch event might solidify its position in the premium smartphone market.", 
              "category": "technology",
              "quarter": "Q4"
          },
          { 
              "_id": "vec3", 
              "chunk_text": "AAPL'\''s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production.",
              "category": "technology",
              "quarter": "Q3"
          },
          { 
              "_id": "vec4", 
              "chunk_text": "AAPL may consider healthcare integrations in Q4 to compete with tech rivals entering the consumer wellness space.", 
              "category": "technology",
              "quarter": "Q4"
          }
      ]);
      ```

      ```java Java theme={null}
      import io.pinecone.clients.Index;
      import io.pinecone.configs.PineconeConfig;
      import io.pinecone.configs.PineconeConnection;
      import org.openapitools.db_data.client.ApiException;

      import java.util.*;

      public class UpsertText {
          public static void main(String[] args) throws ApiException {
              PineconeConfig config = new PineconeConfig("YOUR_API_KEY");
              config.setHost("INDEX_HOST");
              PineconeConnection connection = new PineconeConnection(config);

              Index index = new Index(config, connection, "integrated-sparse-java");
              ArrayList<Map<String, String>> upsertRecords = new ArrayList<>();

              HashMap<String, String> record1 = new HashMap<>();
              record1.put("_id", "rec1");
              record1.put("category", "digestive system");
              record1.put("chunk_text", "Apples are a great source of dietary fiber, which supports digestion and helps maintain a healthy gut.");

              HashMap<String, String> record2 = new HashMap<>();
              record2.put("_id", "rec2");
              record2.put("category", "cultivation");
              record2.put("chunk_text", "Apples originated in Central Asia and have been cultivated for thousands of years, with over 7,500 varieties available today.");

              HashMap<String, String> record3 = new HashMap<>();
              record3.put("_id", "rec3");
              record3.put("category", "immune system");
              record3.put("chunk_text", "Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases.");

              HashMap<String, String> record4 = new HashMap<>();
              record4.put("_id", "rec4");
              record4.put("category", "endocrine system");
              record4.put("chunk_text", "The high fiber content in apples can also help regulate blood sugar levels, making them a favorable snack for people with diabetes.");

              upsertRecords.add(record1);
              upsertRecords.add(record2);
              upsertRecords.add(record3);
              upsertRecords.add(record4);

              index.upsertRecords("example-namespace", upsertRecords);
          }
      }
      ```

      ```go Go theme={null}
      package main

      import (
          "context"
          "fmt"
          "log"

          "github.com/pinecone-io/go-pinecone/v4/pinecone"
      )

      func main() {
          ctx := context.Background()

          pc, err := pinecone.NewClient(pinecone.NewClientParams{
              ApiKey: "YOUR_API_KEY",
          })
          if err != nil {
              log.Fatalf("Failed to create Client: %v", err)
          }

          // To get the unique host for an index, 
          // see https://docs.pinecone.io/guides/manage-data/target-an-index
          idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST", Namespace: "example-namespace"})
          if err != nil {
              log.Fatalf("Failed to create IndexConnection for Host: %v", err)
      	  }

          // Upsert records into a namespace
          // `chunk_text` fields are converted to sparse vectors
          // `category` and `quarter` fields are stored as metadata
      	records := []*pinecone.IntegratedRecord{
      		{
      			"_id":        "vec1",
      			"chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.",
      			"category":   "technology",
      			"quarter":    "Q3",
      		},
      		{
      			"_id":        "vec2",
      			"chunk_text": "Analysts suggest that AAPL's upcoming Q4 product launch event might solidify its position in the premium smartphone market.",
      			"category":   "technology",
      			"quarter":    "Q4",
      		},
      		{
      			"_id":        "vec3",
      			"chunk_text": "AAPL's strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production.",
      			"category":   "technology",
      			"quarter":    "Q3",
      		},
      		{
      			"_id":        "vec4",
      			"chunk_text": "AAPL may consider healthcare integrations in Q4 to compete with tech rivals entering the consumer wellness space.",
      			"category":   "technology",
      			"quarter":    "Q4",
      		},
      	}

      	err = idxConnection.UpsertRecords(ctx, records)
      	if err != nil {
      		log.Fatalf("Failed to upsert vectors: %v", err)
      	}
      }
      ```

      ```shell curl theme={null}
      INDEX_HOST="INDEX_HOST"
      NAMESPACE="YOUR_NAMESPACE"
      PINECONE_API_KEY="YOUR_API_KEY"

      curl  "https://$INDEX_HOST/records/namespaces/$NAMESPACE/upsert" \
          -H "Content-Type: application/x-ndjson" \
          -H "Api-Key: $PINECONE_API_KEY" \
          -H "X-Pinecone-Api-Version: 2025-10" \
          -d '{ "_id": "vec1", "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.", "category": "technology", "quarter": "Q3" }
            { "_id": "vec2", "chunk_text": "Analysts suggest that AAPL'\''s upcoming Q4 product launch event might solidify its position in the premium smartphone market.", "category": "technology", "quarter": "Q4" }
            { "_id": "vec3", "chunk_text": "AAPL'\''s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production.", "category": "technology", "quarter": "Q3" }
            { "_id": "vec4", "chunk_text": "AAPL may consider healthcare integrations in Q4 to compete with tech rivals entering the consumer wellness space.", "category": "technology", "quarter": "Q4" }'
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Upsert vectors">
    To upsert sparse vectors into an [index of sparse vectors](/guides/index-data/create-an-index#create-an-index-for-sparse-vectors), use the [`upsert`](/reference/api/latest/data-plane/upsert) operation as follows:

    * Specify the [`namespace`](/guides/index-data/indexing-overview#namespaces) to upsert into. If the namespace doesn't exist, it is created. To use the default namespace, set the namespace to `"__default__"`.
    * Format your input data as records, each with the following:
      * An `id` field with a unique record identifier for the index namespace.
      * A `sparse_values` field with the sparse vector values and indices.
      * Optionally, a `metadata` field with [key-value pairs](/guides/index-data/indexing-overview#metadata) to store additional information or context. When you query the index, you can use metadata to [filter search results](/guides/search/filter-by-metadata).

    For example, the following code upserts sparse vector representations of sentences related to the term "apple", with the source text and additional fields stored as metadata:

    <CodeGroup>
      ```python Python theme={null}
      from pinecone import Pinecone, SparseValues, Vector

      pc = Pinecone(api_key="YOUR_API_KEY")

      # To get the unique host for an index, 
      # see https://docs.pinecone.io/guides/manage-data/target-an-index
      index = pc.Index(host="INDEX_HOST")

      index.upsert(
          namespace="example-namespace",
          vectors=[
              {
                  "id": "vec1",
                  "sparse_values": {
                      "values": [1.7958984, 0.41577148, 2.828125, 2.8027344, 2.8691406, 1.6533203, 5.3671875, 1.3046875, 0.49780273, 0.5722656, 2.71875, 3.0820312, 2.5019531, 4.4414062, 3.3554688],
                      "indices": [822745112, 1009084850, 1221765879, 1408993854, 1504846510, 1596856843, 1640781426, 1656251611, 1807131503, 2543655733, 2902766088, 2909307736, 3246437992, 3517203014, 3590924191]
                  },
                  "metadata": {
                      "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.",
                      "category": "technology",
                      "quarter": "Q3"
                  }
              },
              {
                  "id": "vec2",
                  "sparse_values": {
                      "values": [0.4362793, 3.3457031, 2.7714844, 3.0273438, 3.3164062, 5.6015625, 2.4863281, 0.38134766, 1.25, 2.9609375, 0.34179688, 1.4306641, 0.34375, 3.3613281, 1.4404297, 2.2558594, 2.2597656, 4.8710938, 0.5605469],
                      "indices": [131900689, 592326839, 710158994, 838729363, 1304885087, 1640781426, 1690623792, 1807131503, 2066971792, 2428553208, 2548600401, 2577534050, 3162218338, 3319279674, 3343062801, 3476647774, 3485013322, 3517203014, 4283091697]
                  },
                  "metadata": {
                      "chunk_text": "Analysts suggest that AAPL'\''s upcoming Q4 product launch event might solidify its position in the premium smartphone market.",
                      "category": "technology",
                      "quarter": "Q4"
                  }
              },
              {
                  "id": "vec3",
                  "sparse_values": {
                      "values": [2.6875, 4.2929688, 3.609375, 3.0722656, 2.1152344, 5.78125, 3.7460938, 3.7363281, 1.2695312, 3.4824219, 0.7207031, 0.0826416, 4.671875, 3.7011719, 2.796875, 0.61621094],
                      "indices": [8661920, 350356213, 391213188, 554637446, 1024951234, 1640781426, 1780689102, 1799010313, 2194093370, 2632344667, 2641553256, 2779594451, 3517203014, 3543799498, 3837503950, 4283091697]
                  },
                  "metadata": {
                      "chunk_text": "AAPL'\''s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production",
                      "category": "technology",
                      "quarter": "Q3"
                  }
              },
              {
                  "id": "vec4",
                  "sparse_values": {
                      "values": [0.73046875, 0.46972656, 2.84375, 5.2265625, 3.3242188, 1.9863281, 0.9511719, 0.5019531, 4.4257812, 3.4277344, 0.41308594, 4.3242188, 2.4179688, 3.1757812, 1.0224609, 2.0585938, 2.5859375],
                      "indices": [131900689, 152217691, 441495248, 1640781426, 1851149807, 2263326288, 2502307765, 2641553256, 2684780967, 2966813704, 3162218338, 3283104238, 3488055477, 3530642888, 3888762515, 4152503047, 4177290673]
                  },
                  "metadata": {
                      "chunk_text": "AAPL may consider healthcare integrations in Q4 to compete with tech rivals entering the consumer wellness space.",
                      "category": "technology",
                      "quarter": "Q4"
                  }
              }
          ]
      )
      ```

      ```javascript JavaScript theme={null}
      import { Pinecone } from '@pinecone-database/pinecone'

      const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' });

      // To get the unique host for an index, 
      // see https://docs.pinecone.io/guides/manage-data/target-an-index
      const index = pc.index("INDEX_NAME", "INDEX_HOST")

      await index.namespace('example-namespace').upsert({ records: [
        {
          id: 'vec1',
          sparseValues: {
            indices: [822745112, 1009084850, 1221765879, 1408993854, 1504846510, 1596856843, 1640781426, 1656251611, 1807131503, 2543655733, 2902766088, 2909307736, 3246437992, 3517203014, 3590924191],
            values: [1.7958984, 0.41577148, 2.828125, 2.8027344, 2.8691406, 1.6533203, 5.3671875, 1.3046875, 0.49780273, 0.5722656, 2.71875, 3.0820312, 2.5019531, 4.4414062, 3.3554688]
          },
          metadata: { 
            chunk_text: 'AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.', 
            category: 'technology',
            quarter: 'Q3' 
          }
        },
        {
          id: 'vec2',
          sparseValues: {
            indices: [131900689, 592326839, 710158994, 838729363, 1304885087, 1640781426, 1690623792, 1807131503, 2066971792, 2428553208, 2548600401, 2577534050, 3162218338, 3319279674, 3343062801, 3476647774, 3485013322, 3517203014, 4283091697],
            values: [0.4362793, 3.3457031, 2.7714844, 3.0273438, 3.3164062, 5.6015625, 2.4863281, 0.38134766, 1.25, 2.9609375, 0.34179688, 1.4306641, 0.34375, 3.3613281, 1.4404297, 2.2558594, 2.2597656, 4.8710938, 0.5605469]
          },
          metadata: { 
            chunk_text: "Analysts suggest that AAPL's upcoming Q4 product launch event might solidify its position in the premium smartphone market.", 
            category: 'technology',
            quarter: 'Q4' 
          }
        },
        {
          id: 'vec3',
          sparseValues: {
            indices: [8661920, 350356213, 391213188, 554637446, 1024951234, 1640781426, 1780689102, 1799010313, 2194093370, 2632344667, 2641553256, 2779594451, 3517203014, 3543799498, 3837503950, 4283091697],
            values: [2.6875, 4.2929688, 3.609375, 3.0722656, 2.1152344, 5.78125, 3.7460938, 3.7363281, 1.2695312, 3.4824219, 0.7207031, 0.0826416, 4.671875, 3.7011719, 2.796875, 0.61621094]
          },
          metadata: { 
            chunk_text: "AAPL's strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production", 
            category: 'technology',
            quarter: 'Q3' 
          }
        },
        {
          id: 'vec4',
          sparseValues: {
            indices: [131900689, 152217691, 441495248, 1640781426, 1851149807, 2263326288, 2502307765, 2641553256, 2684780967, 2966813704, 3162218338, 3283104238, 3488055477, 3530642888, 3888762515, 4152503047, 4177290673],
            values: [0.73046875, 0.46972656, 2.84375, 5.2265625, 3.3242188, 1.9863281, 0.9511719, 0.5019531, 4.4257812, 3.4277344, 0.41308594, 4.3242188, 2.4179688, 3.1757812, 1.0224609, 2.0585938, 2.5859375]
          },
          metadata: { 
            chunk_text: 'AAPL may consider healthcare integrations in Q4 to compete with tech rivals entering the consumer wellness space.', 
            category: 'technology',
            quarter: 'Q4' 
          }
        }
      ] });
      ```

      ```java Java theme={null}
      import io.pinecone.clients.Pinecone;
      import io.pinecone.clients.Index;
      import com.google.protobuf.Struct;
      import com.google.protobuf.Value;

      import java.util.*;

      public class UpsertSparseVectors {
          public static void main(String[] args) throws InterruptedException {
              // Instantiate Pinecone class
              Pinecone pinecone = new Pinecone.Builder("YOUR_API)KEY").build();
              
              Index index = pinecone.getIndexConnection("docs-example");

              // Record 1
              ArrayList<Long> indices1 = new ArrayList<>(Arrays.asList(
                      822745112L, 1009084850L, 1221765879L, 1408993854L, 1504846510L,
                      1596856843L, 1640781426L, 1656251611L, 1807131503L, 2543655733L,
                      2902766088L, 2909307736L, 3246437992L, 3517203014L, 3590924191L
              ));

              ArrayList<Float> values1 = new ArrayList<>(Arrays.asList(
                      1.7958984f, 0.41577148f, 2.828125f, 2.8027344f, 2.8691406f,
                      1.6533203f, 5.3671875f, 1.3046875f, 0.49780273f, 0.5722656f,
                      2.71875f, 3.0820312f, 2.5019531f, 4.4414062f, 3.3554688f
              ));

              Struct metaData1 = Struct.newBuilder()
                      .putFields("chunk_text", Value.newBuilder().setStringValue("AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.").build())
                      .putFields("category", Value.newBuilder().setStringValue("technology").build())
                      .putFields("quarter", Value.newBuilder().setStringValue("Q3").build())
                      .build();

              // Record 2
              ArrayList<Long> indices2 = new ArrayList<>(Arrays.asList(
                      131900689L, 592326839L, 710158994L, 838729363L, 1304885087L,
                      1640781426L, 1690623792L, 1807131503L, 2066971792L, 2428553208L,
                      2548600401L, 2577534050L, 3162218338L, 3319279674L, 3343062801L,
                      3476647774L, 3485013322L, 3517203014L, 4283091697L
              ));

              ArrayList<Float> values2 = new ArrayList<>(Arrays.asList(
                      0.4362793f, 3.3457031f, 2.7714844f, 3.0273438f, 3.3164062f,
                      5.6015625f, 2.4863281f, 0.38134766f, 1.25f, 2.9609375f,
                      0.34179688f, 1.4306641f, 0.34375f, 3.3613281f, 1.4404297f,
                      2.2558594f, 2.2597656f, 4.8710938f, 0.5605469f
              ));

              Struct metaData2 = Struct.newBuilder()
                      .putFields("chunk_text", Value.newBuilder().setStringValue("Analysts suggest that AAPL'\\''s upcoming Q4 product launch event might solidify its position in the premium smartphone market.").build())
                      .putFields("category", Value.newBuilder().setStringValue("technology").build())
                      .putFields("quarter", Value.newBuilder().setStringValue("Q4").build())
                      .build();

              // Record 3
              ArrayList<Long> indices3 = new ArrayList<>(Arrays.asList(
                      8661920L, 350356213L, 391213188L, 554637446L, 1024951234L,
                      1640781426L, 1780689102L, 1799010313L, 2194093370L, 2632344667L,
                      2641553256L, 2779594451L, 3517203014L, 3543799498L,
                      3837503950L, 4283091697L
              ));

              ArrayList<Float> values3 = new ArrayList<>(Arrays.asList(
                      2.6875f, 4.2929688f, 3.609375f, 3.0722656f, 2.1152344f,
                      5.78125f, 3.7460938f, 3.7363281f, 1.2695312f, 3.4824219f,
                      0.7207031f, 0.0826416f, 4.671875f, 3.7011719f, 2.796875f,
                      0.61621094f
              ));

              Struct metaData3 = Struct.newBuilder()
                      .putFields("chunk_text", Value.newBuilder().setStringValue("AAPL'\\''s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production").build())
                      .putFields("category", Value.newBuilder().setStringValue("technology").build())
                      .putFields("quarter", Value.newBuilder().setStringValue("Q3").build())
                      .build();

              // Record 4
              ArrayList<Long> indices4 = new ArrayList<>(Arrays.asList(
                      131900689L, 152217691L, 441495248L, 1640781426L, 1851149807L,
                      2263326288L, 2502307765L, 2641553256L, 2684780967L, 2966813704L,
                      3162218338L, 3283104238L, 3488055477L, 3530642888L, 3888762515L,
                      4152503047L, 4177290673L
              ));

              ArrayList<Float> values4 = new ArrayList<>(Arrays.asList(
                      0.73046875f, 0.46972656f, 2.84375f, 5.2265625f, 3.3242188f,
                      1.9863281f, 0.9511719f, 0.5019531f, 4.4257812f, 3.4277344f,
                      0.41308594f, 4.3242188f, 2.4179688f, 3.1757812f, 1.0224609f,
                      2.0585938f, 2.5859375f
              ));

              Struct metaData4 = Struct.newBuilder()
                      .putFields("chunk_text", Value.newBuilder().setStringValue("AAPL may consider healthcare integrations in Q4 to compete with tech rivals entering the consumer wellness space").build())
                      .putFields("category", Value.newBuilder().setStringValue("technology").build())
                      .putFields("quarter", Value.newBuilder().setStringValue("Q4").build())
                      .build();

              index.upsert("vec1", Collections.emptyList(), indices1, values1, metaData1, "example-namespace");
              index.upsert("vec2", Collections.emptyList(), indices2, values2, metaData2, "example-namespace");
              index.upsert("vec3", Collections.emptyList(), indices3, values3, metaData3, "example-namespace");
              index.upsert("vec4", Collections.emptyList(), indices4, values4, metaData4, "example-namespace");
      ```

      ```go Go theme={null}
      package main

      import (
      	"context"
      	"fmt"
      	"log"

      	"github.com/pinecone-io/go-pinecone/v4/pinecone"
      	"google.golang.org/protobuf/types/known/structpb"
      )

      func main() {
      	ctx := context.Background()

      	pc, err := pinecone.NewClient(pinecone.NewClientParams{
      		ApiKey: "YOUR_API_KEY",
      	})
      	if err != nil {
      		log.Fatalf("Failed to create Client: %v", err)
      	}

      	// To get the unique host for an index,
      	// see https://docs.pinecone.io/guides/manage-data/target-an-index
      	idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST", Namespace: "example-namespace"})
      	if err != nil {
      		log.Fatalf("Failed to create IndexConnection for Host: %v", err)
      	}

      	sparseValues1 := pinecone.SparseValues{
      		Indices: []uint32{822745112, 1009084850, 1221765879, 1408993854, 1504846510, 1596856843, 1640781426, 1656251611, 1807131503, 2543655733, 2902766088, 2909307736, 3246437992, 3517203014, 3590924191},
      		Values:  []float32{1.7958984, 0.41577148, 2.828125, 2.8027344, 2.8691406, 1.6533203, 5.3671875, 1.3046875, 0.49780273, 0.5722656, 2.71875, 3.0820312, 2.5019531, 4.4414062, 3.3554688},
      	}

      	metadataMap1 := map[string]interface{}{
      		"chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones",
      		"category":    "technology",
      		"quarter":     "Q3",
      	}

      	metadata1, err := structpb.NewStruct(metadataMap1)
      	if err != nil {
      		log.Fatalf("Failed to create metadata map: %v", err)
      	}

      	sparseValues2 := pinecone.SparseValues{
      		Indices: []uint32{131900689, 592326839, 710158994, 838729363, 1304885087, 1640781426, 1690623792, 1807131503, 2066971792, 2428553208, 2548600401, 2577534050, 3162218338, 3319279674, 3343062801, 3476647774, 3485013322, 3517203014, 4283091697},
      		Values:  []float32{0.4362793, 3.3457031, 2.7714844, 3.0273438, 3.3164062, 5.6015625, 2.4863281, 0.38134766, 1.25, 2.9609375, 0.34179688, 1.4306641, 0.34375, 3.3613281, 1.4404297, 2.2558594, 2.2597656, 4.8710938, 0.560546},
      	}

      	metadataMap2 := map[string]interface{}{
      		"chunk_text": "Analysts suggest that AAPL's upcoming Q4 product launch event might solidify its position in the premium smartphone market.",
      		"category":    "technology",
      		"quarter":     "Q4",
      	}

      	metadata2, err := structpb.NewStruct(metadataMap2)
      	if err != nil {
      		log.Fatalf("Failed to create metadata map: %v", err)
      	}

      	sparseValues3 := pinecone.SparseValues{
      		Indices: []uint32{8661920, 350356213, 391213188, 554637446, 1024951234, 1640781426, 1780689102, 1799010313, 2194093370, 2632344667, 2641553256, 2779594451, 3517203014, 3543799498, 3837503950, 4283091697},
      		Values:  []float32{2.6875, 4.2929688, 3.609375, 3.0722656, 2.1152344, 5.78125, 3.7460938, 3.7363281, 1.2695312, 3.4824219, 0.7207031, 0.0826416, 4.671875, 3.7011719, 2.796875, 0.61621094},
      	}

      	metadataMap3 := map[string]interface{}{
      		"chunk_text": "AAPL's strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production",
      		"category":    "technology",
      		"quarter":     "Q3",
      	}

      	metadata3, err := structpb.NewStruct(metadataMap3)
      	if err != nil {
      		log.Fatalf("Failed to create metadata map: %v", err)
      	}

      	sparseValues4 := pinecone.SparseValues{
      		Indices: []uint32{131900689, 152217691, 441495248, 1640781426, 1851149807, 2263326288, 2502307765, 2641553256, 2684780967, 2966813704, 3162218338, 3283104238, 3488055477, 3530642888, 3888762515, 4152503047, 4177290673},
      		Values:  []float32{0.73046875, 0.46972656, 2.84375, 5.2265625, 3.3242188, 1.9863281, 0.9511719, 0.5019531, 4.4257812, 3.4277344, 0.41308594, 4.3242188, 2.4179688, 3.1757812, 1.0224609, 2.0585938, 2.5859375},
      	}

      	metadataMap4 := map[string]interface{}{
      		"chunk_text": "AAPL may consider healthcare integrations in Q4 to compete with tech rivals entering the consumer wellness space.",
      		"category":    "technology",
      		"quarter":     "Q4",
      	}

      	metadata4, err := structpb.NewStruct(metadataMap4)
      	if err != nil {
      		log.Fatalf("Failed to create metadata map: %v", err)
      	}

      	vectors := []*pinecone.Vector{
      		{
      			Id:           "vec1",
      			SparseValues: &sparseValues1,
      			Metadata:     metadata1,
      		},
      		{
      			Id:           "vec2",
      			SparseValues: &sparseValues2,
      			Metadata:     metadata2,
      		},
      		{
      			Id:           "vec3",
      			SparseValues: &sparseValues3,
      			Metadata:     metadata3,
      		},
      		{
      			Id:           "vec4",
      			SparseValues: &sparseValues4,
      			Metadata:     metadata4,
      		},
      	}

      	count, err := idxConnection.UpsertVectors(ctx, vectors)
      	if err != nil {
      		log.Fatalf("Failed to upsert vectors: %v", err)
      	} else {
      		fmt.Printf("Successfully upserted %d vector(s)!\n", count)
      	}
      }
      ```

      ```shell curl theme={null}
      INDEX_HOST="INDEX_HOST"
      PINECONE_API_KEY="YOUR_API_KEY"

      curl "http://$INDEX_HOST/vectors/upsert" \
        -H "Content-Type: application/json" \
        -H "Api-Key: $PINECONE_API_KEY" \
        -H "X-Pinecone-Api-Version: 2025-10" \
        -d '{
              "namespace": "example-namespace",
              "vectors": [
                  {
                      "id": "vec1",
                      "sparseValues": {
                          "values": [1.7958984, 0.41577148, 2.828125, 2.8027344, 2.8691406, 1.6533203, 5.3671875, 1.3046875, 0.49780273, 0.5722656, 2.71875, 3.0820312, 2.5019531, 4.4414062, 3.3554688],
                          "indices": [822745112, 1009084850, 1221765879, 1408993854, 1504846510, 1596856843, 1640781426, 1656251611, 1807131503, 2543655733, 2902766088, 2909307736, 3246437992, 3517203014, 3590924191]
                      },
                      "metadata": {
                          "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.",
                          "category": "technology",
                          "quarter": "Q3"
                      }
                  },
                  {
                      "id": "vec2",
                      "sparseValues": {
                          "values": [0.4362793, 3.3457031, 2.7714844, 3.0273438, 3.3164062, 5.6015625, 2.4863281, 0.38134766, 1.25, 2.9609375, 0.34179688, 1.4306641, 0.34375, 3.3613281, 1.4404297, 2.2558594, 2.2597656, 4.8710938, 0.5605469],
                          "indices": [131900689, 592326839, 710158994, 838729363, 1304885087, 1640781426, 1690623792, 1807131503, 2066971792, 2428553208, 2548600401, 2577534050, 3162218338, 3319279674, 3343062801, 3476647774, 3485013322, 3517203014, 4283091697]
                      },
                      "metadata": {
                          "chunk_text": "Analysts suggest that AAPL'\''s upcoming Q4 product launch event might solidify its position in the premium smartphone market.",
                          "category": "technology",
                          "quarter": "Q4"
                      }
                  },
                  {
                      "id": "vec3",
                      "sparseValues": {
                          "values": [2.6875, 4.2929688, 3.609375, 3.0722656, 2.1152344, 5.78125, 3.7460938, 3.7363281, 1.2695312, 3.4824219, 0.7207031, 0.0826416, 4.671875, 3.7011719, 2.796875, 0.61621094],
                          "indices": [8661920, 350356213, 391213188, 554637446, 1024951234, 1640781426, 1780689102, 1799010313, 2194093370, 2632344667, 2641553256, 2779594451, 3517203014, 3543799498, 3837503950, 4283091697]
                      },
                      "metadata": {
                          "chunk_text": "AAPL'\''s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production",
                          "category": "technology",
                          "quarter": "Q3"
                      }
                  },
                  {
                      "id": "vec4",
                      "sparseValues": {
                          "values": [0.73046875, 0.46972656, 2.84375, 5.2265625, 3.3242188, 1.9863281, 0.9511719, 0.5019531, 4.4257812, 3.4277344, 0.41308594, 4.3242188, 2.4179688, 3.1757812, 1.0224609, 2.0585938, 2.5859375],
                          "indices": [131900689, 152217691, 441495248, 1640781426, 1851149807, 2263326288, 2502307765, 2641553256, 2684780967, 2966813704, 3162218338, 3283104238, 3488055477, 3530642888, 3888762515, 4152503047, 4177290673]
                      },
                      "metadata": {
                          "chunk_text": "AAPL may consider healthcare integrations in Q4 to compete with tech rivals entering the consumer wellness space.",
                          "category": "technology",
                          "quarter": "Q4"
                      }
                  },
              ]
          }'
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Upsert documents

Documents are the unit of data in an index with a document schema; see [Document](/guides/get-started/concepts#document) for the definition. Each field in a document is indexed according to the configuration you declared for it in the schema, not just its type — for example, a `string` field can be indexed for BM25 via the `full_text_search` config, and a separate `dense_vector` field can store vector values you provide at upsert time. Indexes with document schemas do not support integrated inference fields such as `semantic_text`.

The example below upserts two documents into the `articles` namespace using the document API. Each document is indexed for BM25 ranking on `body`. The `category` field is upserted as metadata — it isn't declared in the schema but is auto-indexed for filtering at upsert time:

```bash theme={null}
curl -X POST "https://INDEX_HOST/namespaces/articles/documents/upsert" \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Pinecone-Api-Version: 2026-01.alpha" \
  -d '{
    "documents": [
      {
        "_id": "doc1",
        "body": "Pinecone serverless indexes scale automatically with your workload.",
        "category": "platform"
      },
      {
        "_id": "doc2",
        "body": "Full-text search uses BM25 ranking on text fields with full-text search enabled.",
        "category": "search"
      }
    ]
  }'
```

<Note>
  The document API is in public preview and uses the `2026-01.alpha` API version. Indexes with dense or sparse vectors use the stable `2025-10` API version shown in the upsert examples above.
</Note>

Field-name rules:

* Fields not declared in the schema are stored on the document, returned via `include_fields`, and automatically indexed for filtering as metadata. The schema declares only ranking fields (FTS-enabled `string`, `dense_vector`, `sparse_vector`).
* Field names must be unique, non-empty strings, must not start with `_` (reserved for system-managed fields like `_id` and `_score`) or `$` (reserved for filter operators), and are limited to 64 bytes.

Document upsert limits:

* Each upsert request can contain up to 1000 documents and must be no larger than 2 MB.
* Each document can be no larger than 2 MB.
* Each `full_text_search` string field can be no larger than 100 KB and can contain up to 10,000 tokens.
* Each token can be no larger than 256 bytes before analyzer truncation.
* Metadata fields on a document (everything outside FTS-enabled `string` fields) are limited to 40 KB per document in total. This limit does not apply to `full_text_search` text fields.

For the full upsert reference (SDK examples, batching, and the response schema), see [Full-text search](/guides/search/full-text-search).

## Upsert in batches

<Tip>
  To control costs when ingesting large datasets (10,000,000+ records), use [import](/guides/index-data/import-data) instead of upsert.
</Tip>

Send upserts in batches to help increase throughput.

* When upserting records with vectors, a batch should be as large as possible (up to 1000 records) without exceeding the [max request size of 2 MB](#upsert-limits).

  To understand the number of records you can fit into one batch based on the vector dimensions and metadata size, see the following table:

  | Dimension | Metadata (bytes) | Max batch size |
  | :-------- | :--------------- | :------------- |
  | 386       | 0                | 1000           |
  | 768       | 500              | 559            |
  | 1536      | 2000             | 245            |

* When upserting records with text, a batch can contain up to 96 records. This limit comes from the [hosted embedding models](/guides/index-data/create-an-index#embedding-models) used during integrated embedding rather than the batch size limit for upserting raw vectors.

<CodeGroup>
  ```Python Python theme={null}
  import random
  import itertools
  from pinecone.grpc import PineconeGRPC as Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")

  # To get the unique host for an index, 
  # see https://docs.pinecone.io/guides/manage-data/target-an-index
  index = pc.Index(host="INDEX_HOST")

  def chunks(iterable, batch_size=200):
      """A helper function to break an iterable into chunks of size batch_size."""
      it = iter(iterable)
      chunk = tuple(itertools.islice(it, batch_size))
      while chunk:
          yield chunk
          chunk = tuple(itertools.islice(it, batch_size))

  vector_dim = 128
  vector_count = 10000

  # Example generator that generates many (id, vector) pairs
  example_data_generator = map(lambda i: (f'id-{i}', [random.random() for _ in range(vector_dim)]), range(vector_count))

  # Upsert data with 200 vectors per upsert request
  for ids_vectors_chunk in chunks(example_data_generator, batch_size=200):
      index.upsert(vectors=ids_vectors_chunk) 
  ```

  ```JavaScript JavaScript theme={null}
  import { Pinecone } from "@pinecone-database/pinecone";

  const RECORD_COUNT = 10000;
  const RECORD_DIMENSION = 128;

  const client = new Pinecone({ apiKey: "YOUR_API_KEY" });
  const index = client.index("docs-example");

  // A helper function that breaks an array into chunks of size batchSize
  const chunks = (array, batchSize = 200) => {
    const chunks = [];

    for (let i = 0; i < array.length; i += batchSize) {
      chunks.push(array.slice(i, i + batchSize));
    }

    return chunks;
  };

  // Example data generation function, creates many (id, vector) pairs
  const generateExampleData = () =>
    Array.from({ length: RECORD_COUNT }, (_, i) => {
      return {
        id: `id-${i}`,
        values: Array.from({ length: RECORD_DIMENSION }, (_, i) => Math.random()),
      };
    });

  const exampleRecordData = generateExampleData();
  const recordChunks = chunks(exampleRecordData);

  // Upsert data with 200 records per upsert request
  for (const chunk of recordChunks) {
    await index.upsert({ records: chunk })
  }
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Index;
  import io.pinecone.configs.PineconeConfig;
  import io.pinecone.configs.PineconeConnection;
  import io.pinecone.unsigned_indices_model.VectorWithUnsignedIndices;

  import java.util.Arrays;
  import java.util.List;

  public class UpsertBatchExample  {
      public static void main(String[] args) {
          PineconeConfig config = new PineconeConfig("YOUR_API_KEY");
          // To get the unique host for an index, 
          // see https://docs.pinecone.io/guides/manage-data/target-an-index
          config.setHost("INDEX_HOST");
          PineconeConnection connection = new PineconeConnection(config);
          Index index = new Index(connection, "INDEX_NAME");

          ArrayList<VectorWithUnsignedIndices> vectors = generateVectors();
          ArrayList<ArrayList<VectorWithUnsignedIndices>> chunks = chunks(vectors, BATCH_SIZE);

          for (ArrayList<VectorWithUnsignedIndices> chunk : chunks) {
              index.upsert(chunk, "example-namespace");
          }
      }

      // A helper function that breaks an ArrayList into chunks of batchSize
      private static ArrayList<ArrayList<VectorWithUnsignedIndices>> chunks(ArrayList<VectorWithUnsignedIndices> vectors, int batchSize) {
          ArrayList<ArrayList<VectorWithUnsignedIndices>> chunks = new ArrayList<>();
          ArrayList<VectorWithUnsignedIndices> chunk = new ArrayList<>();

          for (int i = 0; i < vectors.size(); i++) {
              if (i % BATCH_SIZE == 0 && i != 0) {
                  chunks.add(chunk);
                  chunk = new ArrayList<>();
              }

              chunk.add(vectors.get(i));
          }

          return chunks;
      }

      // Example data generation function, creates many (id, vector) pairs
      private static ArrayList<VectorWithUnsignedIndices> generateVectors() {
          Random random = new Random();
          ArrayList<VectorWithUnsignedIndices> vectors = new ArrayList<>();


          for (int i = 0; i <= RECORD_COUNT; i++) {
              String id = "id-" + i;
              ArrayList<Float> values = new ArrayList<>();

              for (int j = 0; j < RECORD_DIMENSION; j++) {
                  values.add(random.nextFloat());
              }

              VectorWithUnsignedIndices vector = new VectorWithUnsignedIndices();
              vector.setId(id);
              vector.setValues(values);
              vectors.add(vector);
          }

          return vectors;
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "fmt"
      "log"

      "github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

      // To get the unique host for an index, 
      // see https://docs.pinecone.io/guides/manage-data/target-an-index
      idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST"})
      if err != nil {
          log.Fatalf("Failed to create IndexConnection for Host: %v", err)
  	  }

      // Generate a large number of vectors to upsert
      vectorCount := 10000
      vectorDim := idx.Dimension

      vectors := make([]*pinecone.Vector, vectorCount)
      for i := 0; i < int(vectorCount); i++ {
          randomFloats := make([]float32, vectorDim)

          for i := int32(0); i < vectorDim; i++ {
              randomFloats[i] = rand.Float32()
          }

          vectors[i] = &pinecone.Vector{
              Id:     fmt.Sprintf("doc1#-vector%d", i),
              Values: randomFloats,
          }
      }

      // Break the vectors into batches of 200
      var batches [][]*pinecone.Vector
      batchSize := 200

      for len(vectors) > 0 {
          batchEnd := batchSize
          if len(vectors) < batchSize {
              batchEnd = len(vectors)
          }
          batches = append(batches, vectors[:batchEnd])
          vectors = vectors[batchEnd:]
      }

      // Upsert batches
      for i, batch := range batches {
          upsertResp, err := idxConn.UpsertVectors(context.Background(), batch)
          if err != nil {
              panic(err)
          }

          fmt.Printf("upserted %d vectors (%v of %v batches)\n", upsertResp, i+1, len(batches))
      }
  }
  ```
</CodeGroup>

## Upsert in parallel

<Tip>
  Python SDK v6.0.0 and later provide `async` methods for use with [asyncio](https://docs.python.org/3/library/asyncio.html). Asyncio support makes it possible to use Pinecone with modern async web frameworks such as FastAPI, Quart, and Sanic. For more details, see [Async requests](/reference/sdks/python/overview#async-requests).
</Tip>

Send multiple upserts in parallel to help increase throughput. Vector operations block until the response has been received. However, they can be made asynchronously as follows:

<CodeGroup>
  ```Python Python theme={null}
  # This example uses `async_req=True` and multiple threads.
  # For a single-threaded approach compatible with modern async web frameworks, 
  # see https://docs.pinecone.io/reference/sdks/python/overview#async-requests
  import random
  import itertools
  from pinecone import Pinecone

  # Initialize the client with pool_threads=30. This limits simultaneous requests to 30.
  pc = Pinecone(api_key="YOUR_API_KEY", pool_threads=30)

  # To get the unique host for an index, 
  # see https://docs.pinecone.io/guides/manage-data/target-an-index
  index = pc.Index(host="INDEX_HOST")

  def chunks(iterable, batch_size=200):
      """A helper function to break an iterable into chunks of size batch_size."""
      it = iter(iterable)
      chunk = tuple(itertools.islice(it, batch_size))
      while chunk:
          yield chunk
          chunk = tuple(itertools.islice(it, batch_size))

  vector_dim = 128
  vector_count = 10000

  example_data_generator = map(lambda i: (f'id-{i}', [random.random() for _ in range(vector_dim)]), range(vector_count))

  # Upsert data with 200 vectors per upsert request asynchronously
  # - Pass async_req=True to index.upsert()
  with pc.Index(host="INDEX_HOST", pool_threads=30) as index:
      # Send requests in parallel
      async_results = [
          index.upsert(vectors=ids_vectors_chunk, async_req=True)
          for ids_vectors_chunk in chunks(example_data_generator, batch_size=200)
      ]
      # Wait for and retrieve responses (this raises in case of error)
      [async_result.get() for async_result in async_results]
  ```

  ```JavaScript JavaScript theme={null}
  import { Pinecone } from "@pinecone-database/pinecone";

  const RECORD_COUNT = 10000;
  const RECORD_DIMENSION = 128;

  const client = new Pinecone({ apiKey: "YOUR_API_KEY" });

  // To get the unique host for an index, 
  // see https://docs.pinecone.io/guides/manage-data/target-an-index
  const index = pc.index("INDEX_NAME", "INDEX_HOST")

  // A helper function that breaks an array into chunks of size batchSize
  const chunks = (array, batchSize = 200) => {
    const chunks = [];

    for (let i = 0; i < array.length; i += batchSize) {
      chunks.push(array.slice(i, i + batchSize));
    }

    return chunks;
  };

  // Example data generation function, creates many (id, vector) pairs
  const generateExampleData = () =>
    Array.from({ length: RECORD_COUNT }, (_, i) => {
      return {
        id: `id-${i}`,
        values: Array.from({ length: RECORD_DIMENSION }, (_, i) => Math.random()),
      };
    });

  const exampleRecordData = generateExampleData();
  const recordChunks = chunks(exampleRecordData);

  // Upsert data with 200 records per request asynchronously using Promise.all()
  await Promise.all(recordChunks.map((chunk) => index.upsert({ records: chunk })));
  ```

  ```java Java theme={null}
  import com.google.protobuf.Struct;
  import com.google.protobuf.Value;
  import io.pinecone.clients.Index;
  import io.pinecone.configs.PineconeConfig;
  import io.pinecone.configs.PineconeConnection;
  import io.pinecone.proto.UpsertResponse;
  import io.pinecone.unsigned_indices_model.VectorWithUnsignedIndices;

  import java.util.ArrayList;
  import java.util.Arrays;
  import java.util.concurrent.ExecutorService;
  import java.util.concurrent.Executors;
  import java.util.List;

  public class UpsertExample {
      public static void main(String[] args) {
          PineconeConfig config = new PineconeConfig("YOUR_API_KEY");
          // To get the unique host for an index, 
          // see https://docs.pinecone.io/guides/manage-data/target-an-index
          config.setHost("INDEX_HOST");
          PineconeConnection connection = new PineconeConnection(config);
          Index index = new Index(connection, "INDEX_NAME");

          // Run 5 threads concurrently and upsert data into pinecone
          int numberOfThreads = 5;

          // Create a fixed thread pool
          ExecutorService executor = Executors.newFixedThreadPool(numberOfThreads);

          // Submit tasks to the executor
          for (int i = 0; i < numberOfThreads; i++) {
              // upsertData
              int batchNumber = i+1;
              executor.submit(() -> upsertData(index, batchNumber));
          }

          // Shutdown the executor
          executor.shutdown();
      }

      private static void upsertData(Index index, int batchNumber) {
          // Vector ids to be upserted
          String prefix = "v" + batchNumber;
          List<String> upsertIds = Arrays.asList(prefix + "_1", prefix + "_2", prefix + "_3");

          // List of values to be upserted
          List<List<Float>> values = new ArrayList<>();
          values.add(Arrays.asList(1.0f, 2.0f, 3.0f));
          values.add(Arrays.asList(4.0f, 5.0f, 6.0f));
          values.add(Arrays.asList(7.0f, 8.0f, 9.0f));

          // List of sparse indices to be upserted
          List<List<Long>> sparseIndices = new ArrayList<>();
          sparseIndices.add(Arrays.asList(1L, 2L, 3L));
          sparseIndices.add(Arrays.asList(4L, 5L, 6L));
          sparseIndices.add(Arrays.asList(7L, 8L, 9L));

          // List of sparse values to be upserted
          List<List<Float>> sparseValues = new ArrayList<>();
          sparseValues.add(Arrays.asList(1000f, 2000f, 3000f));
          sparseValues.add(Arrays.asList(4000f, 5000f, 6000f));
          sparseValues.add(Arrays.asList(7000f, 8000f, 9000f));

          List<VectorWithUnsignedIndices> vectors = new ArrayList<>(3);

          // Metadata to be upserted
          Struct metadataStruct1 = Struct.newBuilder()
                  .putFields("genre", Value.newBuilder().setStringValue("action").build())
                  .putFields("year", Value.newBuilder().setNumberValue(2019).build())
                  .build();

          Struct metadataStruct2 = Struct.newBuilder()
                  .putFields("genre", Value.newBuilder().setStringValue("thriller").build())
                  .putFields("year", Value.newBuilder().setNumberValue(2020).build())
                  .build();

          Struct metadataStruct3 = Struct.newBuilder()
                  .putFields("genre", Value.newBuilder().setStringValue("comedy").build())
                  .putFields("year", Value.newBuilder().setNumberValue(2021).build())
                  .build();
          List<Struct> metadataStructList = Arrays.asList(metadataStruct1, metadataStruct2, metadataStruct3);

          // Upsert data
          for (int i = 0; i < metadataStructList.size(); i++) {
              vectors.add(buildUpsertVectorWithUnsignedIndices(upsertIds.get(i), values.get(i), sparseIndices.get(i), sparseValues.get(i), metadataStructList.get(i)));
          }

          UpsertResponse upsertResponse = index.upsert(vectors, "example-namespace");
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "fmt"
      "log"
      "math/rand"
      "sync"
      
      "github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

      // To get the unique host for an index, 
      // see https://docs.pinecone.io/guides/manage-data/target-an-index
      idxConn, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST"})
      if err != nil {
          log.Fatalf("Failed to create IndexConnection for Host: %v", err)
  	  }

      // Generate a large number of vectors to upsert
      vectorCount := 10000
      vectorDim := idx.Dimension

      vectors := make([]*pinecone.Vector, vectorCount)
      for i := 0; i < int(vectorCount); i++ {
          randomFloats := make([]float32, vectorDim)

          for i := int32(0); i < vectorDim; i++ {
              randomFloats[i] = rand.Float32()
          }

          vectors[i] = &pinecone.Vector{
              Id:     fmt.Sprintf("doc1#-vector%d", i),
              Values: randomFloats,
          }
      }

      // Break the vectors into batches of 200
      var batches [][]*pinecone.Vector
      batchSize := 200

      for len(vectors) > 0 {
          batchEnd := batchSize
          if len(vectors) < batchSize {
              batchEnd = len(vectors)
          }
          batches = append(batches, vectors[:batchEnd])
          vectors = vectors[batchEnd:]
      }

      // Use channels to manage concurrency and possible errors
      maxConcurrency := 10
      errChan := make(chan error, len(batches))
      semaphore := make(chan struct{}, maxConcurrency)
      var wg sync.WaitGroup

      for i, batch := range batches {
          wg.Add(1)
          semaphore <- struct{}{}

          go func(batch []*pinecone.Vector, i int) {
              defer wg.Done()
              defer func() { <-semaphore }()

              upsertResp, err := idxConn.UpsertVectors(context.Background(), batch)
              if err != nil {
                  errChan <- fmt.Errorf("batch %d failed: %v", i, err)
                  return
              }

              fmt.Printf("upserted %d vectors (%v of %v batches)\n", upsertResp, i+1, len(batches))
          }(batch, i)
      }

      wg.Wait()
      close(errChan)

      for err := range errChan {
          if err != nil {
              fmt.Printf("Error while upserting batch: %v\n", err)
          }
      }
  }
  ```
</CodeGroup>

### Python SDK with gRPC

Using the Python SDK with gRPC extras can provide higher upsert speeds. Through multiplexing, gRPC is able to handle large amounts of requests in parallel without slowing down the rest of the system (HoL blocking), unlike REST. Moreover, you can pass various retry strategies to the gRPC SDK, including [exponential backoff](/guides/production/error-handling#implement-retry-logic).

To install the gRPC version of the SDK:

```Shell Shell theme={null}
pip install "pinecone[grpc]"
```

To use the gRPC SDK, import the `pinecone.grpc` subpackage and target an index as usual:

```Python Python theme={null}
from pinecone.grpc import PineconeGRPC as Pinecone

# This is gRPC client aliased as "Pinecone"
pc = Pinecone(api_key='YOUR_API_KEY')  

# To get the unique host for an index, 
# see https://docs.pinecone.io/guides/manage-data/target-an-index
index = pc.Index(host="INDEX_HOST")
```

To launch multiple read and write requests in parallel, pass `async_req` to the `upsert` operation:

```Python Python theme={null}
def chunker(seq, batch_size):
  return (seq[pos:pos + batch_size] for pos in range(0, len(seq), batch_size))

async_results = [
  index.upsert(vectors=chunk, async_req=True)
  for chunk in chunker(data, batch_size=200)
]

# Wait for and retrieve responses (in case of error)
[async_result.result() for async_result in async_results]
```

<Note>
  It is possible to get write-throttled faster when upserting using the gRPC SDK. If you see this often, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) while upserting.

  The syntax for upsert, query, fetch, and delete with the gRPC SDK remain the same as the standard SDK.
</Note>

## Upsert limits

| Metric                                                             | Limit                                                         |
| :----------------------------------------------------------------- | :------------------------------------------------------------ |
| Max [batch size](/guides/index-data/upsert-data#upsert-in-batches) | 2 MB or 1000 records with vectors <br /> 96 records with text |
| Max documents per upsert request                                   | 1000                                                          |
| Max document upsert request size                                   | 2 MB                                                          |
| Max document size                                                  | 2 MB                                                          |
| Max `full_text_search` string fields per schema                    | 100                                                           |
| Max size per `full_text_search` string field                       | 100 KB                                                        |
| Max tokens per `full_text_search` string field                     | 10,000                                                        |
| Max bytes per token                                                | 256 bytes                                                     |
| Max filterable metadata size per document                          | 40 KB                                                         |
| Max length for a record ID                                         | 512 characters                                                |
| Max dimensionality for dense vectors                               | 20,000                                                        |
| Max non-zero values for sparse vectors                             | 2048                                                          |
| Max dimensionality for sparse vectors                              | 4.2 billion                                                   |

The 40 KB filterable metadata limit does not apply to `full_text_search` text fields.


# Back up a pod-based index
Source: https://docs.pinecone.io/guides/indexes/pods/back-up-a-pod-based-index

Legacy guide for backing up Pinecone pod-based indexes using collections. Collections are a pod-only feature not available for serverless indexes.

<Warning>
  Customers who sign up for a Standard or Enterprise plan on or after August 18, 2025 cannot create pod-based indexes. Instead, create [serverless indexes](/guides/index-data/create-an-index), and consider using [dedicated read nodes](/guides/index-data/dedicated-read-nodes) for large workloads (millions of records or more, and moderate or high query rates).
</Warning>

This page describes how to create a static copy of a pod-based index, also known as a [collection](/guides/indexes/pods/understanding-collections).

## Create a collection

To create a backup of your pod-based index, use the [`create_collection`](/reference/api/latest/control-plane/create_collection) operation.

The following example creates a [collection](/guides/indexes/pods/understanding-collections) named `example-collection` from an index named `docs-example`:

<CodeGroup>
  ```python Python theme={null}
  # pip install "pinecone[grpc]"
  from pinecone.grpc import PineconeGRPC as Pinecone

  pc = Pinecone(api_key="API_KEY")
  pc.create_collection("example-collection", "docs-example")
  ```

  ```javascript JavaScript theme={null}
  // npm install @pinecone-database/pinecone
  import { Pinecone } from '@pinecone-database/pinecone'

  const pc = new Pinecone({
    apiKey: 'YOUR_API_KEY'
  });

  await pc.createCollection({
    name: "example-collection",
    source: "docs-example",
  });
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Pinecone;

  public class CreateCollectionExample {
      public static void main(String[] args) {
          Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build();

          pc.createCollection("example-collection", "docs-example");
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "fmt"
      "log"

      "github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

      collection, err := pc.CreateCollection(ctx, &pinecone.CreateCollectionRequest{
          Name: "example-collection", 
          Source: "docs-example",
      })
      if err != nil {
          log.Fatalf("Failed to create collection: %v", err)
      } else {
          fmt.Printf("Successfully created collection: %v", collection.Name)
      }
  }
  ```

  ```shell curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"

  curl -s POST "https://api.pinecone.io/collections" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2025-10" \
    -d '{
          "name": "example-collection",
          "source": "docs-example"
    }'
  ```
</CodeGroup>

<Tip>
  You can create a collection using the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/backups).
</Tip>

## Check the status of a collection

To retrieve the status of the process creating a collection and the size of the collection, use the [`describe_collection`](/reference/api/latest/control-plane/describe_collection) operation. Specify the name of the collection to check. You can only call `describe_collection` on a collection in the current project.

The `describe_collection` operation returns an object containing key-value pairs representing the name of the collection, the size in bytes, and the creation status of the collection.

The following example gets the creation status and size of a collection named `example-collection`.

<CodeGroup>
  ```python Python theme={null}
  # pip install "pinecone[grpc]"
  from pinecone.grpc import PineconeGRPC as Pinecone

  pc = Pinecone(api_key='API_KEY')
  pc.describe_collection(name="example-collection")
  ```

  ```javascript JavaScript theme={null}
  // npm install @pinecone-database/pinecone
  import { Pinecone } from '@pinecone-database/pinecone';

  const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' });

  await pc.describeCollection('example-collection');
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Pinecone;
  import org.openapitools.client.model.CollectionModel;

  public class DescribeCollectionExample {
      public static void main(String[] args) {
          Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build();
          CollectionModel collectionModel = pc.describeCollection("example-collection");
          System.out.println(collectionModel);
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "fmt"
      "log"

      "github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

      collectionName := "example-collection"

      collection, err := pc.DescribeCollection(ctx, collectionName)
      if err != nil {
          log.Fatalf("Error describing collection %v: %v", collectionName, err)
      } else {
          fmt.Printf("Collection: %+v", collection)
      }
  }
  ```

  ```shell curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"

  curl -i -X GET "https://api.pinecone.io/collections/example-collection" \
      -H "Api-Key: $PINECONE_API_KEY" \
      -H "X-Pinecone-Api-Version: 2025-10"
  ```
</CodeGroup>

<Tip>
  You can check the status of a collection using the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/backups).
</Tip>

## List your collections

To get a list of the collections in the current project, use the [`list_collections`](/reference/api/latest/control-plane/list_collections) operation.

<CodeGroup>
  ```python Python theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone

  pc = Pinecone(api_key='API_KEY')
  pc.list_collections()
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone'

  const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' })

  await pc.listCollections();
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Pinecone;
  import org.openapitools.client.model.CollectionModel;

  public class ListCollectionsExample {
      public static void main(String[] args) {
          Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build();
          List<CollectionModel> collectionList = pc.listCollections().getCollections();
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "encoding/json"
      "fmt"
      "log"

      "github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func prettifyStruct(obj interface{}) string {
      bytes, _ := json.MarshalIndent(obj, "", "  ")
      return string(bytes)
  }

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

      collections, err := pc.ListCollections(ctx)
      if err != nil {
  	    log.Fatalf("Failed to list collections: %v", err)
      } else {
          if len(collections) == 0 {
              fmt.Printf("No collections found in project")
          } else {
              for _, collection := range collections {
                  fmt.Printf("collection: %v\n", prettifyStruct(collection))
              }
          }
      }
  }
  ```

  ```shell curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"

  curl -i -X GET "https://api.pinecone.io/collections" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2025-10"
  ```

  <Tip>
    You can view a list of your collections using the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/backups).
  </Tip>
</CodeGroup>

<Tip>
  You can view a list of your collections using the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/backups).
</Tip>

## Delete a collection

To delete a collection, use the [`delete_collection`](/reference/api/latest/control-plane/delete_collection) operation. Specify the name of the collection to delete.

Deleting the collection takes several minutes. During this time, the [`describe_collection`](#check-the-status-of-a-collection) operation returns the status "deleting".

<CodeGroup>
  ```python Python theme={null}
  # pip install "pinecone[grpc]"
  from pinecone.grpc import PineconeGRPC as Pinecone

  pc = Pinecone(api_key='API_KEY')
  pc.delete_collection("example-collection")
  ```

  ```javascript JavaScript theme={null}
  // npm install @pinecone-database/pinecone
  import { Pinecone } from '@pinecone-database/pinecone'

  const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' })

  await pc.deleteCollection("example-collection");
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Pinecone;

  public class DeleteCollectionExample {
      public static void main(String[] args) {
          Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build();
          pc.deleteCollection("example-collection");
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "fmt"
      "log"

      "github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

      collectionName := "example-collection"

      err = pc.DeleteCollection(ctx, collectionName)
      if err != nil {
  	    log.Fatalf("Failed to delete collection: %v\n", err)
      } else {
          if len(collections) == 0 {
              fmt.Printf("No collections found in project")
          } else {
              fmt.Printf("Successfully deleted collection \"%v\"\n", collectionName)
          }
      }
  }
  ```

  ```shell curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"

  curl -i -X DELETE "https://api.pinecone.io/collections/example-collection" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2025-10"
  ```
</CodeGroup>

<Tip>
  You can delete a collection using the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/backups).
</Tip>


# Choose a pod type and size
Source: https://docs.pinecone.io/guides/indexes/pods/choose-a-pod-type-and-size

Choose a Pinecone pod type and size (s1, p1, p2). Legacy guide: pods are unavailable to new customers as of August 2025; serverless needs no planning.

<Warning>
  Customers who sign up for a Standard or Enterprise plan on or after August 18, 2025 cannot create pod-based indexes. Instead, create [serverless indexes](/guides/index-data/create-an-index), and consider using [dedicated read nodes](/guides/index-data/dedicated-read-nodes) for large workloads (millions of records or more, and moderate or high query rates).
</Warning>

When planning your Pinecone deployment, it is important to understand the approximate storage requirements of your vectors to choose the appropriate pod type and number. This page will give guidance on sizing to help you plan accordingly.

As with all guidelines, these considerations are general and may not apply to your specific use case. We caution you to always test your deployment and ensure that the index configuration you are using is appropriate to your requirements.

[Collections](/guides/indexes/pods/understanding-collections) allow you to create new versions of your index with different pod types and sizes. This also allows you to test different configurations. This guide is merely an overview of sizing considerations; test your index configuration before moving to production.

<Tip>
  Users on Standard and Enterprise plans can [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) for further help with sizing and testing.
</Tip>

## Overview

There are five main considerations when deciding how to configure your Pinecone index:

* Number of vectors
* Dimensionality of your vectors
* Size of metadata on each vector
* Queries per second (QPS) throughput
* Cardinality of indexed metadata

Each of these considerations comes with requirements for index size, pod type, and replication strategy.

### Number of vectors

The most important consideration in sizing is the [number of vectors](/guides/index-data/upsert-data) you plan on working with. As a rule of thumb, a single p1 pod can store approximately 1M vectors, while a s1 pod can store 5M vectors. However, this can be affected by other factors, such as dimensionality and metadata, which are explained below.

### Dimensionality of vectors

The rules of thumb above for how many vectors can be stored in a given pod assumes a typical configuration of 768 [dimensions per vector](/guides/index-data/create-an-index). As your individual use case will dictate the dimensionality of your vectors, the amount of space required to store them may necessarily be larger or smaller.

Each dimension on a single vector consumes 4 bytes of memory and storage per dimension, so if you expect to have 1M vectors with 768 dimensions each, that’s about 3GB of storage without factoring in metadata or other overhead. Using that reference, we can estimate the typical pod size and number needed for a given index. Table 1 below gives some examples of this.

**Table 1: Estimated number of pods per 1M vectors by dimensionality**

| Pod type | Dimensions | Estimated max vectors per pod |
| -------- | ---------: | ----------------------------: |
| **p1**   |        512 |                     1,250,000 |
|          |        768 |                     1,000,000 |
|          |       1024 |                       675,000 |
|          |       1536 |                       500,000 |
| **p2**   |        512 |                     1,250,000 |
|          |        768 |                     1,100,000 |
|          |       1024 |                     1,000,000 |
|          |       1536 |                       550,000 |
| **s1**   |        512 |                     8,000,000 |
|          |        768 |                     5,000,000 |
|          |       1024 |                     4,000,000 |
|          |       1536 |                     2,500,000 |

Pinecone does not support fractional pod deployments, so always round up to the next nearest whole number when choosing your pods.

## Queries per second (QPS)

QPS speeds are governed by a combination of the [pod type](/guides/indexes/pods/understanding-pod-based-indexes#pod-types) of the index, the number of [replicas](/guides/indexes/pods/scale-pod-based-indexes#add-replicas), and the `top_k` value of queries. The pod type is the primary factor driving QPS, as the different pod types are optimized for different approaches.

The [p1 pods](/guides/index-data/indexing-overview/#p1-pods) are performance-optimized pods which provide very low query latencies, but hold fewer vectors per pod than [s1 pods](/guides/index-data/indexing-overview/#s1-pods). They are ideal for applications with low latency requirements (\<100ms). The s1 pods are optimized for storage and provide large storage capacity and lower overall costs with slightly higher query latencies than p1 pods. They are ideal for very large indexes with moderate or relaxed latency requirements.

The [p2 pod type](/guides/index-data/indexing-overview/#p2-pods) provides greater query throughput with lower latency. They support 200 QPS per replica and return queries in less than 10ms. This means that query throughput and latency are better than s1 and p1, especially for low dimension vectors (\<512D).

As a rule, a single p1 pod with 1M vectors of 768 dimensions each and no replicas can handle about 20 QPS. It’s possible to get greater or lesser speeds, depending on the size of your metadata, number of vectors, the dimensionality of your vectors, and the `top_K` value for your search. See Table 2 below for more examples.

**Table 2: QPS by pod type and `top_k` value**\*

| Pod type | top\_k 10 | top\_k 250 | top\_k 1000 |
| -------- | --------- | ---------- | ----------- |
| p1       | 30        | 25         | 20          |
| p2       | 150       | 50         | 20          |
| s1       | 10        | 10         | 10          |

\*The QPS values in Table 2 represent baseline QPS with 1M vectors and 768 dimensions.

[Adding replicas](/guides/indexes/pods/scale-pod-based-indexes#add-replicas) is the simplest way to increase your QPS. Each replica increases the throughput potential by roughly the same QPS, so aiming for 150 QPS using p1 pods means using the primary pod and 5 replicas. Using threading or multiprocessing in your application is also important, as issuing single queries sequentially still subjects you to delays from any underlying latency. The [Pinecone gRPC SDK](/guides/index-data/upsert-data#grpc-python-sdk) can also be used to increase throughput of upserts.

### Metadata cardinality and size

The last consideration when planning your indexes is the cardinality and size of your [metadata](/guides/index-data/upsert-data#inserting-vectors-with-metadata). While the increases are small when talking about a few million vectors, they can have a real impact as you grow to hundreds of millions or billions of vectors.

Indexes with very high cardinality, like those storing a unique user ID on each vector, can have significant memory requirements, resulting in fewer vectors fitting per pod. Also, if the size of the metadata per vector is larger, the index requires more storage. Limiting which metadata fields are indexed using [selective metadata indexing](/guides/indexes/pods/manage-pod-based-indexes#selective-metadata-indexing) can help lower memory usage.

### Pod sizes

You can also start with one of the larger [pod sizes](/guides/index-data/indexing-overview/#pod-size-and-performance), like p1.x2. Each step up in pod size doubles the space available for your vectors. We recommend starting with x1 pods and scaling as you grow. This way, you don’t start with too large a pod size and have nowhere else to go up, meaning you have to migrate to a new index before you’re ready.

### Example applications

The following examples will showcase how to use the sizing guidelines above to choose the appropriate type, size, and number of pods for your index.

#### Example 1: Semantic search of news articles

In our first example, we’ll use the demo app for semantic search from our documentation. In this case, we’re only working with 204,135 vectors. The vectors use 300 dimensions each, well under the general measure of 768 dimensions. Using the rule of thumb above of up to 1M vectors per p1 pod, we can run this app comfortably with a single p1.x1 pod.

#### Example 2: Facial recognition

For this example, suppose you’re building an application to identify customers using facial recognition for a secure banking app. Facial recognition can work with as few as 128 dimensions, but in this case, because the app will be used for access to finances, we want to make sure we’re certain that the person using it is the right one. We plan for 100M customers and use 2048 dimensions per vector.

We know from our rules of thumb above that 1M vectors with 768 dimensions fit nicely in a p1.x1 pod. We can just divide those numbers into the new targets to get the ratios we’ll need for our pod estimate:

```
100M / 1M = 100 base p1 pods
2048 / 768 = 2.667 vector ratio
2.667 * 100 = 267 rounding up
```

So we need 267 p1.x1 pods. We can reduce that by switching to s1 pods instead, sacrificing latency by increasing storage availability. They hold five times the storage of p1.x1, so the math is simple:

```
267 / 5 = 54 rounding up
```

So we estimate that we need 54 s1.x1 pods to store very high dimensional data for the face of each of the bank’s customers.


# Create a pod-based index
Source: https://docs.pinecone.io/guides/indexes/pods/create-a-pod-based-index

Create a Pinecone pod-based index. Legacy guide: new customers cannot create pod indexes as of August 2025; use serverless index creation instead.

<Warning>
  Customers who sign up for a Standard or Enterprise plan on or after August 18, 2025 cannot create pod-based indexes. Instead, create [serverless indexes](/guides/index-data/create-an-index), and consider using [dedicated read nodes](/guides/index-data/dedicated-read-nodes) for large workloads (millions of records or more, and moderate or high query rates).
</Warning>

This page shows you how to create a pod-based index. For guidance on serverless indexes, see [Create a serverless index](/guides/index-data/create-an-index).

## Create a pod index

To create a pod index, use the [`create_index`](/reference/api/latest/control-plane/create_index) operation as follows:

* Provide a `name` for the index.
* Specify the `dimension` and `metric` of the vectors you'll store in the index. This should match the dimension and metric supported by your embedding model.
* Set `spec.environment` to the [environment](/guides/index-data/create-an-index#cloud-regions) where the index should be deployed. For Python, you also need to import the `ServerlessSpec` class.
* Set `spec.pod_type` to the [pod type](/guides/indexes/pods/understanding-pod-based-indexes#pod-types) and [size](/guides/index-data/indexing-overview#pod-size-and-performance) that you want.

Other parameters are optional. See the [API reference](/reference/api/latest/control-plane/create_index) for details.

<CodeGroup>
  ```Python Python theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone, PodSpec

  pc = Pinecone(api_key="YOUR_API_KEY")

  pc.create_index(
    name="docs-example",
    dimension=1536,
    metric="cosine",
    spec=PodSpec(
      environment="us-west1-gcp",
      pod_type="p1.x1",
      pods=1
    ),
    deletion_protection="disabled"

  )
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone'

  const pc = new Pinecone({
    apiKey: 'YOUR_API_KEY'
  });

  await pc.createIndex({
    name: 'docs-example',
    dimension: 1536,
    metric: 'cosine',
    spec: {
      pod: {
        environment: 'us-west1-gcp',
        podType: 'p1.x1',
        pods: 1
      }
    },
    deletionProtection: 'disabled',
  });
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Pinecone;
  import org.openapitools.db_control.client.model.IndexModel;
  import org.openapitools.db_control.client.model.DeletionProtection;

  public class CreateIndexExample {
      public static void main(String[] args) {
          Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build();
          pc.createPodsIndex("docs-example", 1536, "us-west1-gcp",
                  "p1.x1", "cosine", DeletionProtection.DISABLED);
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "fmt"
      "log"

      "github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

      indexName := "docs-example"
    	metric := pinecone.Dotproduct
  	  deletionProtection := pinecone.DeletionProtectionDisabled

      idx, err := pc.CreatePodIndex(ctx, &pinecone.CreatePodIndexRequest{
          Name:               indexName,
          Metric:             &metric,
          Dimension:          1536,
          Environment:        "us-east1-gcp",
          PodType:            "p1.x1",
          DeletionProtection: &deletionProtection,
      })
      if err != nil {
          log.Fatalf("Failed to create pod-based index: %v", idx.Name)
      } else {
          fmt.Printf("Successfully created pod-based index: %v", idx.Name)
      }
  }
  ```

  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"

  curl -s "https://api.pinecone.io/indexes" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2025-10" \
    -d '{
           "name": "docs-example",
           "dimension": 1536,
           "metric": "cosine",
           "spec": {
              "pod": {
                 "environment": "us-west1-gcp",
                 "pod_type": "p1.x1",
                 "pods": 1
              }
           },
           "deletion_protection": "disabled"
        }'
  ```
</CodeGroup>

## Create a pod index from a collection

You can create a pod-based index from a collection. For more details, see [Restore an index](/guides/indexes/pods/restore-a-pod-based-index).


# Manage pod-based indexes
Source: https://docs.pinecone.io/guides/indexes/pods/manage-pod-based-indexes

Manage Pinecone pod-based indexes. Legacy guide: pod indexes are unavailable to new customers as of August 2025; serverless is recommended for new projects.

<Warning>
  Customers who sign up for a Standard or Enterprise plan on or after August 18, 2025 cannot create pod-based indexes. Instead, create [serverless indexes](/guides/index-data/create-an-index), and consider using [dedicated read nodes](/guides/index-data/dedicated-read-nodes) for large workloads (millions of records or more, and moderate or high query rates).
</Warning>

This page shows you how to manage pod-based indexes.

For guidance on serverless indexes, see [Manage serverless indexes](/guides/manage-data/manage-indexes).

## Describe a pod-based index

Use the [`describe_index`](/reference/api/latest/control-plane/describe_index/) endpoint to get a complete description of a specific index:

<CodeGroup>
  ```Python Python theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")

  pc.describe_index(name="docs-example")

  # Response:
  # {'dimension': 1536,
  #  'host': 'docs-example-4mkljsz.svc.aped-4627-b74a.pinecone.io',
  #  'metric': 'cosine',
  #  'name': 'docs-example',
  #  'spec': {'pod': {'environment': 'us-east-1-aws',
  #                   'pod_type': 's1.x1',
  #                   'pods': 1,
  #                   'replicas': 1,
  #                   'shards': 1}},
  #  'status': {'ready': True, 'state': 'Ready'}}
  ```

  ```JavaScript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone';

  const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' });

  await pc.describeIndex('docs-example');

  // Response:
  // {
  //    "name": "docs-example",
  //    "dimension": 1536,
  //    "metric": "cosine",
  //    "host": "docs-example-4mkljsz.svc.aped-4627-b74a.pinecone.io",
  //    "deletionProtection": "disabled",
  //    "spec": {
  //       "pod": {
  //          "environment": "us-east-1-aws",
  //          "pod_type": "s1.x1",
  //          "pods": 1,
  //          "replicas": 1,
  //          "shards": 1
  //       }
  //    },
  //    "status": {
  //       "ready": true,
  //       "state": "Ready"
  //    }
  // }
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Pinecone;
  import org.openapitools.db_control.client.model.*;

  public class DescribeIndexExample {
      public static void main(String[] args) {
          Pinecone pc = new Pinecone.Builder("YOURE_API_KEY").build();
          IndexModel indexModel = pc.describeIndex("docs-example");
          System.out.println(indexModel);
      }
  }

  // Response:
  // class IndexModel {
  //     name: docs-example
  //     dimension: 1536
  //     metric: cosine
  //     host: docs-example-4mkljsz.svc.aped-4627-b74a.pinecone.io
  //     deletionProtection: disabled
  //     spec: class IndexModelSpec {
  //         serverless: null
  //         pod: class PodSpec {
  //             cloud: aws
  //             region: us-east-1
  //             environment: us-east-1-aws,
  //             podType: s1.x1,
  //             pods: 1,
  //             replicas: 1,
  //             shards: 1
  //         }
  //     }
  //     status: class IndexModelStatus {
  //         ready: true
  //         state: Ready
  //     }
  // }
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "encoding/json"
      "fmt"
      "log"

      "github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func prettifyStruct(obj interface{}) string {
      bytes, _ := json.MarshalIndent(obj, "", "  ")
      return string(bytes)
  }

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

      idx, err := pc.DescribeIndex(ctx, "docs-example")
      if err != nil {
          log.Fatalf("Failed to describe index \"%v\": %v", idx.Name, err)
      } else {
          fmt.Printf("index: %v\n", prettifyStruct(idx))
      }
  }

  // Response:
  // index: {
  // 	"name": "docs-example",
  // 	"dimension": 1536,
  // 	"host": "docs-example-4mkljsz.svc.aped-4627-b74a.pinecone.io",
  // 	"metric": "cosine",
  //  "deletion_protection": "disabled",
  // 	"spec": {
  // 	  "pod": {
  //       "environment": "us-east-1-aws",
  //       "pod_type": "s1.x1",
  //       "pods": 1,
  //       "replicas": 1,
  //       "shards": 1
  // 	  }
  // 	},
  // 	"status": {
  // 	  "ready": true,
  // 	  "state": "Ready"
  // 	}
  // }
  ```

  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"

  curl -i -X GET "https://api.pinecone.io/indexes/docs-example" \
      -H "Api-Key: $PINECONE_API_KEY" \
      -H "X-Pinecone-Api-Version: 2025-10"
  # Response:
  # {
  #    "name": "docs-example",
  #    "metric": "cosine",
  #    "dimension": 1536,
  #    "status": {
  #       "ready": true,
  #       "state": "Ready"
  #    },
  #    "host": "docs-example-4mkljsz.svc.aped-4627-b74a.pinecone.io",
  #    "spec": {
  #       "pod": {
  #          "environment": "us-east-1-aws",
  #          "pod_type": "s1.x1",
  #          "pods": 1,
  #          "replicas": 1,
  #          "shards": 1
  #       }
  #    }
  # }
  ```
</CodeGroup>

<Warning>
  **Do not target an index by name in production.**

  When you target an index by name for data operations such as `upsert` and `query`, the SDK gets the unique DNS host for the index using the `describe_index` operation. This is convenient for testing but should be avoided in production because `describe_index` uses a different API than data operations and therefore adds an additional network call and point of failure. Instead, you should get an index host once and cache it for reuse or specify the host directly.
</Warning>

## Delete a pod-based index

Use the [`delete_index`](/reference/api/latest/control-plane/delete_index) operation to delete a pod-based index and all of its associated resources.

<Note>
  You are billed for a pod-based index even when it is not in use.
</Note>

<CodeGroup>
  ```python Python theme={null}
  # pip install "pinecone[grpc]"
  from pinecone.grpc import PineconeGRPC as Pinecone, PodSpec

  pc = Pinecone(api_key="YOUR_API_KEY")

  pc.delete_index(name="docs-example")
  ```

  ```javascript JavaScript theme={null}
  // npm install @pinecone-database/pinecone
  import { Pinecone } from '@pinecone-database/pinecone'

  const pc = new Pinecone({
    apiKey: 'YOUR_API_KEY'
  });

  await pc.deleteIndex('docs-example');
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Pinecone;

  public class DeleteIndexExample {
      public static void main(String[] args) {
          Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build();
          pc.deleteIndex("docs-example");
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "fmt"
      "log"

      "github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

      indexName := "docs-example"

      err = pc.DeleteIndex(ctx, indexName)
      if err != nil {
          log.Fatalf("Failed to delete index: %v", err)
      } else {
          fmt.Println("Index \"%v\" deleted successfully", indexName)
      }
  }
  ```

  ```shell curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"

  curl -i -X DELETE "https://api.pinecone.io/indexes/docs-example" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2025-10"
  ```
</CodeGroup>

If deletion protection is enabled on an index, requests to delete it will fail and return a `403 - FORBIDDEN` status with the following error:

```
Deletion protection is enabled for this index. Disable deletion protection before retrying.
```

Before you can delete such an index, you must first [disable deletion protection](/guides/manage-data/manage-indexes#configure-deletion-protection).

<Tip>
  You can delete an index using the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/indexes). For the index you want to delete, click the three dots to the right of the index name, then click **Delete**.
</Tip>

## Selective metadata indexing

For pod-based indexes, Pinecone indexes all metadata fields by default. When metadata fields contains many unique values, pod-based indexes will consume significantly more memory, which can lead to performance issues, pod fullness, and a reduction in the number of possible vectors that fit per pod.

To avoid indexing high-cardinality metadata that is not needed for [filtering your queries](/guides/index-data/indexing-overview#metadata) and keep memory utilization low, specify which metadata fields to index using the `metadata_config` parameter.

<Note>
  Since high-cardinality metadata does not cause high memory utilization in serverless indexes, selective metadata indexing is not supported.
</Note>

The value for the `metadata_config` parameter is a JSON object containing the names of the metadata fields to index.

```JSON JSON theme={null}
{
    "indexed": [
        "metadata-field-1",
        "metadata-field-2",
        "metadata-field-n"
    ]
}
```

**Example**

The following example creates a pod-based index that only indexes the `genre` metadata field. Queries against this index that filter for the `genre` metadata field may return results; queries that filter for other metadata fields behave as though those fields do not exist.

<CodeGroup>
  ```Python Python theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone, PodSpec

  pc = Pinecone(api_key="YOUR_API_KEY")

  pc.create_index(
    name="docs-example",
    dimension=1536,
    metric="cosine",
    spec=PodSpec(
      environment="us-west1-gcp",
      pod_type="p1.x1",
      pods=1,
      metadata_config = {
        "indexed": ["genre"]
      }
    ),
    deletion_protection="disabled"

  )
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone'

  const pc = new Pinecone({
    apiKey: 'YOUR_API_KEY'
  });

  await pc.createIndex({
    name: 'docs-example',
    dimension: 1536,
    metric: 'cosine',
    spec: {
      pod: {
        environment: 'us-west1-gcp',
        podType: 'p1.x1',
        pods: 1,
        metadata_config: {
          indexed: ["genre"]
        }
      }
    },
    deletionProtection: 'disabled',
  });
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Pinecone;
  import org.openapitools.db_control.client.model.IndexModel;
  import org.openapitools.db_control.client.model.DeletionProtection;

  public class CreateIndexExample {
      public static void main(String[] args) {
          Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build();
          CreateIndexRequestSpecPodMetadataConfig podSpecMetadataConfig = new CreateIndexRequestSpecPodMetadataConfig();
          List<String> indexedItems = Arrays.asList("genre", "year");
          podSpecMetadataConfig.setIndexed(indexedItems);
          pc.createPodsIndex("docs-example", 1536, "us-west1-gcp",
                  "p1.x1", "cosine", podSpecMetadataConfig, DeletionProtection.DISABLED);
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "fmt"
      "log"

      "github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

      podIndexMetadata := &pinecone.PodSpecMetadataConfig{
          Indexed: &[]string{"genre"},
      }

      indexName := "docs-example"
    	metric := pinecone.Dotproduct
  	deletionProtection := pinecone.DeletionProtectionDisabled

  	idx, err := pc.CreatePodIndex(ctx, &pinecone.CreatePodIndexRequest{
          Name:               indexName,
          Metric:             &metric,
          Dimension:          1536,
          Environment:        "us-east1-gcp",
          PodType:            "p1.x1",
          DeletionProtection: &deletionProtection,
    	})
    	if err != nil {
          log.Fatalf("Failed to create pod-based index: %v", idx.Name)
      } else {
          fmt.Printf("Successfully created pod-based index: %v", idx.Name)
      }
  }
  ```

  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"

  curl -s https://api.pinecone.io/indexes \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2025-10" \
    -d '{
           "name": "docs-example",
           "dimension": 1536,
           "metric": "cosine",
           "spec": {
              "pod": {
                 "environment": "us-west1-gcp",
                 "pod_type": "p1.x1",
                 "pods": 1,
                 "metadata_config": {
                    "indexed": ["genre"]
                 }
              }
           },
           "deletion_protection": "disabled"
        }'
  ```
</CodeGroup>

## Prevent index deletion

<Note>
  This feature requires [Pinecone API version](/reference/api/versioning) `2024-07`, [Python SDK](/reference/sdks/python/overview) v5.0.0, [Node.js SDK](/reference/sdks/node/overview) v3.0.0, [Java SDK](/reference/sdks/java/overview) v2.0.0, or [Go SDK](/reference/sdks/go/overview) v1.0.0 or later.
</Note>

You can prevent an index and its data from accidental deleting when [creating a new index](/guides/index-data/create-an-index) or when [configuring an existing index](/guides/indexes/pods/manage-pod-based-indexes). In both cases, you set the `deletion_protection` parameter to `enabled`.

To enable deletion protection when creating a new index:

<CodeGroup>
  ```python Python theme={null}
  # pip install "pinecone[grpc]"
  from pinecone.grpc import PineconeGRPC as Pinecone, PodSpec

  pc = Pinecone(api_key="YOUR_API_KEY")

  pc.create_index(
    name="docs-example",
    dimension=1536,
    metric="cosine",
    spec=PodSpec(
      environment="us-west1-gcp",
      pod_type="p1.x1",
      pods=1
    ),
      deletion_protection="enabled"
  )
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone'

  const pc = new Pinecone({
    apiKey: 'YOUR_API_KEY'
  });

  await pc.createIndex({
    name: 'docs-example',
    dimension: 1536,
    metric: 'cosine',
    spec: {
      pod: {
        environment: 'us-west1-gcp',
        podType: 'p1.x1',
        pods: 1
      }
    },
    deletionProtection: 'enabled',
  });
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Pinecone;
  import org.openapitools.db_control.client.model.IndexModel;
  import org.openapitools.db_control.client.model.DeletionProtection;

  public class CreateIndexExample {
      public static void main(String[] args) {
          Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build();
          pc.createPodsIndex("docs-example", 1536, "us-west1-gcp",
                  "p1.x1", "cosine", DeletionProtection.ENABLED);
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "fmt"
      "log"

      "github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

      indexName := "docs-example"
    	metric := pinecone.Dotproduct
  	deletionProtection := pinecone.DeletionProtectionDisabled

  	idx, err := pc.CreatePodIndex(ctx, &pinecone.CreatePodIndexRequest{
          Name:               indexName,
          Metric:             &metric,
          Dimension:          1536,
          Environment:        "us-east1-gcp",
          PodType:            "p1.x1",
          DeletionProtection: &deletionProtection,
    	})
    	if err != nil {
          log.Fatalf("Failed to create pod-based index: %v", idx.Name)
      } else {
          fmt.Printf("Successfully created pod-based index: %v", idx.Name)
      }
  }
  ```

  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"

  curl -s "https://api.pinecone.io/indexes" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2025-10" \
    -d '{
           "name": "docs-example",
           "dimension": 1536,
           "metric": "cosine",
           "spec": {
              "pod": {
                 "environment": "us-west1-gcp",
                 "pod_type": "p1.x1",
                 "pods": 1
              }
           },
           "deletion_protection": "enabled"
        }'
  ```
</CodeGroup>

To enable deletion protection when configuring an existing index:

<CodeGroup>
  ```python Python theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")

  pc.configure_index(
     name="docs-example", 
     deletion_protection="enabled"
  )
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone';

  const client = new Pinecone({ apiKey: 'YOUR_API_KEY' });

  await client.configureIndex('docs-example', { deletionProtection: 'enabled' });
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Pinecone;
  import org.openapitools.db_control.client.model.*;

  public class ConfigureIndexExample {
      public static void main(String[] args) {
          Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build();
          pc.configurePodsIndex("docs-example", DeletionProtection.ENABLED);
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "fmt"
      "log"

      "github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

      idx, err := pc.ConfigureIndex(ctx, "docs-example", pinecone.ConfigureIndexParams{DeletionProtection: "enabled"})
    	if err != nil {
          log.Fatalf("Failed to configure index \"%v\": %v", idx.Name, err)
      } else {
          fmt.Printf("Successfully configured index \"%v\"", idx.Name)
      }
  }
  ```

  ```shell curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"

  curl -s -X PATCH "https://api.pinecone.io/indexes/docs-example" \
      -H "Content-Type: application/json" \
      -H "Api-Key: $PINECONE_API_KEY" \
      -H "X-Pinecone-Api-Version: 2025-10" \
      -d '{
          "deletion_protection": "enabled"
          }'
  ```
</CodeGroup>

When deletion protection is enabled on an index, requests to delete the index fail and return a `403 - FORBIDDEN` status with the following error:

```
Deletion protection is enabled for this index. Disable deletion protection before retrying.
```

## Disable deletion protection

Before you can [delete an index](#delete-a-pod-based-index) with deletion protection enabled, you must first disable deletion protection as follows:

<CodeGroup>
  ```python Python theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")

  pc.configure_index(
     name="docs-example", 
     deletion_protection="disabled"
  )
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone';

  const client = new Pinecone({ apiKey: 'YOUR_API_KEY' });

  await client.configureIndex('docs-example', { deletionProtection: 'disabled' });
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Pinecone;
  import org.openapitools.db_control.client.model.*;

  public class ConfigureIndexExample {
      public static void main(String[] args) {
          Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build();
          pc.configurePodsIndex("docs-example", DeletionProtection.DISABLED);
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "fmt"
      "log"

      "github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

      idx, err := pc.ConfigureIndex(ctx, "docs-example", pinecone.ConfigureIndexParams{DeletionProtection: "disabled"})
    	if err != nil {
          log.Fatalf("Failed to configure index \"%v\": %v", idx.Name, err)
      } else {
          fmt.Printf("Successfully configured index \"%v\"", idx.Name)
      }
  }
  ```

  ```shell curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"

  curl -s -X PATCH "https://api.pinecone.io/indexes/docs-example" \
      -H "Content-Type: application/json" \
      -H "Api-Key: $PINECONE_API_KEY" \
      -H "X-Pinecone-Api-Version: 2025-10" \
      -d '{
          "deletion_protection": "disabled"
          }'
  ```
</CodeGroup>

## Delete an entire namespace

In pod-based indexes, reads and writes share compute resources, so deleting an entire namespace with many records can increase the latency of read operations. In such cases, consider [deleting records in batches](#delete-records-in-batches).

## Delete records in batches

In pod-based indexes, reads and writes share compute resources, so deleting an entire namespace or a large number of records can increase the latency of read operations. To avoid this, delete records in batches of up to 1000, with a brief sleep between requests. Consider using smaller batches if the index has active read traffic.

<CodeGroup>
  ```python Batch delete a namespace theme={null}
  from pinecone import Pinecone
  import numpy as np
  import time

  pc = Pinecone(api_key='API_KEY')

  INDEX_NAME = 'INDEX_NAME'
  NAMESPACE = 'NAMESPACE_NAME'
  # Consider using smaller batches if you have a high RPS for read operations
  BATCH = 1000

  index = pc.Index(name=INDEX_NAME)
  dimensions = index.describe_index_stats()['dimension']

  # Create the query vector
  query_vector = np.random.uniform(-1, 1, size=dimensions).tolist()
  results = index.query(vector=query_vector, namespace=NAMESPACE, top_k=BATCH)

  # Delete in batches until the query returns no results
  while len(results['matches']) > 0:
      ids = [i['id'] for i in results['matches']]
      index.delete(ids=ids, namespace=NAMESPACE)
      time.sleep(0.01)
      results = index.query(vector=query_vector, namespace=NAMESPACE, top_k=BATCH)
  ```

  ```python Batch delete by metadata theme={null}
  from pinecone import Pinecone
  import numpy as np
  import time

  pc = Pinecone(api_key='API_KEY')

  INDEX_NAME = 'INDEX_NAME'
  NAMESPACE = 'NAMESPACE_NAME'
  # Consider using smaller batches if you have a high RPS for read operations
  BATCH = 1000

  index = pc.Index(name=INDEX_NAME)
  dimensions = index.describe_index_stats()['dimension']

  METADATA_FILTER = {}

  # Create the query vector with a filter
  query_vector = np.random.uniform(-1, 1, size=dimensions).tolist()
  results = index.query(vector=query_vector, namespace=NAMESPACE, filter=METADATA_FILTER, top_k=BATCH)

  # Delete in batches until the query returns no results
  while len(results['matches']) > 0:
      ids = [i['id'] for i in results['matches']]
      index.delete(ids=ids, namespace=NAMESPACE)
      time.sleep(0.01)
      results = index.query(vector=query_vector, namespace=NAMESPACE, filter=METADATA_FILTER, top_k=BATCH)
  ```
</CodeGroup>

## Delete records by metadata

<Note>
  In pod-based indexes, if you are targeting a large number of records for deletion and the index has active read traffic, consider [deleting records in batches](#delete-records-in-batches).
</Note>

To delete records from a namespace based on their metadata values, pass a [metadata filter expression](/guides/index-data/indexing-overview#metadata-filter-expressions) to the `delete` operation. This deletes all records in the namespace that match the filter expression.

For example, the following code deletes all records with a `genre` field set to `documentary` from namespace `example-namespace`:

<CodeGroup>
  ```Python Python theme={null}
  # pip install "pinecone[grpc]"
  from pinecone.grpc import PineconeGRPC as Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")

  # To get the unique host for an index, 
  # see https://docs.pinecone.io/guides/manage-data/target-an-index
  index = pc.Index(host="INDEX_HOST")

  index.delete(
      filter={
          "genre": {"$eq": "documentary"}
      },
      namespace="example-namespace" 
  )
  ```

  ```JavaScript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone'

  const pc = new Pinecone({ apiKey: "YOUR_API_KEY" })

  // To get the unique host for an index, 
  // see https://docs.pinecone.io/guides/manage-data/target-an-index
  const index = pc.index("INDEX_NAME", "INDEX_HOST")

  const ns = index.namespace('example-namespace')

  await ns.deleteMany({
    genre: { $eq: "documentary" },
  });
  ```

  ```java Java theme={null}
  import com.google.protobuf.Struct;
  import com.google.protobuf.Value;
  import io.pinecone.clients.Index;
  import io.pinecone.configs.PineconeConfig;
  import io.pinecone.configs.PineconeConnection;

  import java.util.Arrays;
  import java.util.List;

  public class DeleteExample {
      public static void main(String[] args) {
          PineconeConfig config = new PineconeConfig("YOUR_API_KEY");
          // To get the unique host for an index, 
          // see https://docs.pinecone.io/guides/manage-data/target-an-index
          config.setHost("INDEX_HOST");
          PineconeConnection connection = new PineconeConnection(config);
          Index index = new Index(connection, "INDEX_NAME");
          Struct filter = Struct.newBuilder()
                  .putFields("genre", Value.newBuilder()
                          .setStructValue(Struct.newBuilder()
                                  .putFields("$eq", Value.newBuilder()
                                          .setStringValue("documentary")
                                          .build()))
                          .build())
                  .build();
          index.deleteByFilter(filter, "example-namespace");
          
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "log"

      "github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

      // To get the unique host for an index, 
      // see https://docs.pinecone.io/guides/manage-data/target-an-index
      idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST", Namespace: "example-namespace"})
      if err != nil {
          log.Fatalf("Failed to create IndexConnection for Host: %v", err)
    	}

      metadataFilter := map[string]interface{}{
  		"genre": map[string]interface{}{
  			"$eq": "documentary",
  		},
      }

      filter, err := structpb.NewStruct(metadataFilter)
      if err != nil {
          log.Fatalf("Failed to create metadata filter: %v", err)
      }

      err = idxConnection.DeleteVectorsByFilter(ctx, filter)
      if err != nil {
          log.Fatalf("Failed to delete vector(s) with filter %+v: %v", filter, err)
      }
  }
  ```

  ```bash curl theme={null}
  # To get the unique host for an index,
  # see https://docs.pinecone.io/guides/manage-data/target-an-index
  PINECONE_API_KEY="YOUR_API_KEY"
  INDEX_HOST="INDEX_HOST"

  curl -i "https://$INDEX_HOST/vectors/delete" \
    -H 'Api-Key: $PINECONE_API_KEY' \
    -H 'Content-Type: application/json' \
    -H "X-Pinecone-Api-Version: 2025-10" \
    -d '{
      "filter": {"genre": {"$eq": "documentary"}},
      "namespace": "example-namespace"
    }'
  ```
</CodeGroup>

## Tag an index

When configuring an index, you can tag the index to help with index organization and management. For more details, see [Tag an index](/guides/manage-data/manage-indexes#configure-index-tags).

## Manage costs

### Set a project pod limit

To control costs, [project owners](/guides/projects/understanding-projects#project-roles) can [set the maximum total number of pods](/reference/api/database-limits#pods-per-project) allowed across all pod-based indexes in a project. The default pod limit is 5.

<Tabs>
  <Tab title="Pinecone console">
    1. Go to [Settings > Projects](https://app.pinecone.io/organizations/-/settings/projects).
    2. For the project you want to update, click the **ellipsis (...) menu > Configure**.
    3. In the **Pod Limit** section, update the number of pods.
    4. Click **Save Changes**.
  </Tab>

  <Tab title="API">
    <token />

    ```bash curl theme={null}
    PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
    PROJECT_ID="YOUR_PROJECT_ID"

    curl -X PATCH "https://api.pinecone.io/admin/projects/$PROJECT_ID" \
      -H "accept: application/json" \
      -H "Content-Type: application/json" \
    	-H "X-Pinecone-Api-Version: 2025-10" \
      -d '{
        "max_pods": 5
        }'
    ```

    The example returns a response like the following:

    ```json theme={null}
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "example-project",
      "max_pods": 5,
      "force_encryption_with_cmek": false,
      "organization_id": "string",
      "created_at": "2025-03-17T00:42:31.912Z"
    }
    ```
  </Tab>
</Tabs>

### Back up inactive pod-based indexes

For each pod-based index, billing is determined by the per-minute price per pod and the number of pods the index uses, regardless of index activity. When a pod-based index is not in use, [back it up using collections](/guides/indexes/pods/back-up-a-pod-based-index) and delete the inactive index. When you're ready to use the vectors again, you can [create a new index from the collection](/guides/indexes/pods/create-a-pod-based-index#create-a-pod-index-from-a-collection). This new index can also use a different index type or size. Because it's relatively cheap to store collections, you can reduce costs by only running an index when it's in use.

### Choose the right index type and size

Pod sizes are designed for different applications, and some are more expensive than others. [Choose the appropriate pod type and size](/guides/indexes/pods/choose-a-pod-type-and-size), so you pay for the resources you need. For example, the `s1` pod type provides large storage capacity and lower overall costs with slightly higher query latencies than `p1` pods. By switching to a different pod type, you may be able to reduce costs while still getting the performance your application needs.

<Note>
  For pod-based indexes, project owners can [set limits for the total number of pods](/reference/api/database-limits#pods-per-project) across all indexes in the project. The default pod limit is 5.
</Note>

## Monitor performance

Pinecone generates time-series performance metrics for each Pinecone index. You can monitor these metrics directly in the Pinecone console or with tools like Prometheus or Datadog.

### Use the Pinecone Console

To view performance metrics in the Pinecone console:

1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects).
2. Select the project containing the index you want to monitor.
3. Go to **Database > Indexes**.
4. Select the index.
5. Go to the **Metrics** tab.

### Use Datadog

To monitor Pinecone with Datadog, use Datadog's [Pinecone integration](/integrations/datadog).

<Note>
  This feature is available on [Standard and Enterprise plans](https://www.pinecone.io/pricing/).
</Note>

### Use Prometheus

<Note>
  This feature is available on [Standard and Enterprise plans](https://www.pinecone.io/pricing/). When using [Bring Your Own Cloud](/guides/production/bring-your-own-cloud), you must configure Prometheus monitoring within your VPC.
</Note>

To monitor all pod-based indexes in a specific region of a project, insert the following snippet into the [`scrape_configs`](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#scrape_config) section of your `prometheus.yml` file and update it with values for your Prometheus integration:

```YAML theme={null}
scrape_configs:
  - job_name: "pinecone-pod-metrics"
    scheme: https
    metrics_path: '/metrics'
    authorization:
      credentials: API_KEY
    static_configs:
      - targets: ["metrics.ENVIRONMENT.pinecone.io" ]
```

* Replace `API_KEY` with an API key for the project you want to monitor. If necessary, you can [create an new API key](/reference/api/authentication) in the Pinecone console.

* Replace `ENVIRONMENT` with the [environment](/guides/indexes/pods/understanding-pod-based-indexes#pod-environments) of the pod-based indexes you want to monitor.

For more configuration details, see the [Prometheus docs](https://prometheus.io/docs/prometheus/latest/configuration/configuration/).

#### Available metrics

The following metrics are available when you integrate Pinecone with Prometheus:

| Name                                 | Type      | Description                                                                       |
| :----------------------------------- | :-------- | :-------------------------------------------------------------------------------- |
| `pinecone_vector_count`              | gauge     | The number of records per pod in the index.                                       |
| `pinecone_request_count_total`       | counter   | The number of data plane calls made by clients.                                   |
| `pinecone_request_error_count_total` | counter   | The number of data plane calls made by clients that resulted in errors.           |
| `pinecone_request_latency_seconds`   | histogram | The distribution of server-side processing latency for pinecone data plane calls. |
| `pinecone_index_fullness`            | gauge     | The fullness of the index on a scale of 0 to 1.                                   |

#### Metric labels

Each metric contains the following labels:

| Label          | Description                                                                                                                                    |
| :------------- | :--------------------------------------------------------------------------------------------------------------------------------------------- |
| `pid`          | Process identifier.                                                                                                                            |
| `index_name`   | Name of the index to which the metric applies.                                                                                                 |
| `project_name` | Name of the project containing the index.                                                                                                      |
| `request_type` | Type of request: `upsert`, `delete`, `fetch`, `query`, or `describe_index_stats`. This label is included only in `pinecone_request_*` metrics. |

#### Example queries

Return the average latency in seconds for all requests against the Pinecone index `docs-example`:

```shell theme={null}
avg by (request_type) (pinecone_request_latency_seconds{index_name="docs-example"})
```

Return the vector count for the Pinecone index `docs-example`:

```shell theme={null}
sum ((avg by (app) (pinecone_vector_count{index_name="docs-example"})))
```

Return the total number of requests against the Pinecone index `docs-example` over one minute:

```shell theme={null}
sum by (request_type)(increase(pinecone_request_count_total{index_name="docs-example"}[60s]))
```

Return the total number of upsert requests against the Pinecone index `docs-example` over one minute:

```shell theme={null}
sum by (request_type)(increase(pinecone_request_count_total{index_name="docs-example", request_type="upsert"}[60s]))
```

Return the total errors returned by the Pinecone index `docs-example` over one minute:

```shell theme={null}
sum by (request_type) (increase(pinecone_request_error_count{
      index_name="docs-example"}[60s]))
```

Return the index fullness metric for the Pinecone index `docs-example`:

```
round(max (pinecone_index_fullness{index_name="docs-example"} * 100))
```

## Troubleshooting

### Index fullness errors

Serverless indexes automatically scale as needed.

However, pod-based indexes can run out of capacity. When that happens, upserting new records will fail with the following error:

```console console theme={null}
Index is full, cannot accept data.
```

### High-cardinality metadata and over-provisioning

This [Loom video walkthrough](https://www.loom.com/share/ce6f5dd0c3e14ba0b988fe32d96b703a?sid=48646dfe-c10c-4143-82c6-031fefe05a68) shows you how to manage two scenarios:

* The first scenario involves customers loading an index replete with high cardinality metadata. This can trigger a series of unforeseen challenges, and hence, it's vital to comprehend how to manage this situation effectively. This methodology can be applied whenever you need to change your metadata configuration.

* The second scenario that we will address involves customers who have over-provisioned the number of pods they need. More specifically, we will discuss the process of re-scaling an index in instances where the customer has previously scaled vertically and now desires to scale the index back down.


# Migrate a pod-based index to serverless
Source: https://docs.pinecone.io/guides/indexes/pods/migrate-a-pod-based-index-to-serverless

Migrate a Pinecone pod-based index to serverless for automatic scaling, better performance, and usage-based pricing with no minimum spend commitment.

This page shows you how to migrate a pod-based index to [serverless](/guides/get-started/database-architecture). The migration process is free; the standard costs of upserting records to a new serverless index are not applied.

<Warning>
  In most cases, migrating to serverless reduces costs significantly. For read-heavy workloads with more than 1 query per second and for indexes with many records in a single namespace, consider building your serverless indexes on [dedicated read nodes](/guides/index-data/dedicated-read-nodes).

  Before migrating, [contact Pinecone Support](/troubleshooting/contact-support) for help estimating and managing cost implications.
</Warning>

## Limitations

Migration is supported for pod-based indexes with less than 25 million records and 20,000 namespaces across all supported clouds (AWS, GCP, and Azure).

Also, serverless indexes do not support the following features. If you were using these features for your pod-based index, you will need to adapt your code. If you are blocked by these limitations, [contact Pinecone Support](/troubleshooting/contact-support).

* [Selective metadata indexing](/guides/indexes/pods/manage-pod-based-indexes#selective-metadata-indexing)

  * Because high-cardinality metadata in serverless indexes does not cause high memory utilization, this operation is not relevant.
* [Filtering index statistics by metadata](/reference/api/latest/data-plane/describeindexstats)

## How it works

Migrating a pod-based index to serverless is a 2-step process:

<Steps>
  <Step title="Save the pod-based index as a collection" />

  <Step title="Create a new serverless index from the collection" />
</Steps>

After migration, you will have both a new serverless index and the original pod-based index. Once you've switched your workload to the serverless index, you can delete the pod-based index to avoid paying for unused resources.

## 1. Understand cost implications

In most cases, migrating to serverless reduces costs significantly. However, costs can increase for read-heavy workloads with more than 1 query per second and for indexes with many records in a single namespace.

Before migrating, consider [contacting Pinecone Support](/troubleshooting/contact-support) for help estimating and managing cost implications.

## 2. Prepare for migration

Migrating a pod-based index to serverless can take anywhere from a few minutes to several hours, depending on the size of the index. During that time, you can continue reading from the pod-based index. However, all [upserts](/guides/index-data/upsert-data), [updates](/guides/manage-data/update-data), and [deletes](/guides/manage-data/delete-data) to the pod-based index will not automatically be reflected in the new serverless index, so be sure to prepare in one of the following ways:

* **Pause write traffic:** If downtime is acceptable, pause traffic to the pod-based index before starting migration. After migration, you will start sending traffic to the serverless index.

* **Log your writes:** If you need to continue reading from the pod-based index during migration, send read traffic to the pod-based index, but log your writes to a temporary location outside of Pinecone (e.g., S3). After migration, you will replay the logged writes to the new serverless index and start sending all traffic to the serverless index.

## 3. Start migration

<Tabs>
  <Tab title="Pinecone console">
    1. In the [Pinecone console](https://app.pinecone.io/), go to your pod-based index and click the **ellipsis (...) menu > Migrate to serverless**.

       <img />

       <Note>
         The dropdown will not display **Migrate to serverless** if the index has any of the listed [limitations](#limitations).
       </Note>

    2. To save the legacy index and create a new serverless index now, follow the prompts.

       Depending on the size of the index, migration can take anywhere from a few minutes to several hours. While migration is in progress, you'll see the yellow **Initializing** status:

       <img alt="create index from collection - initializing status" />

       When the new serverless index is ready, the status will change to green:

       <img alt="create index from collection - ready status" />
  </Tab>

  <Tab title="API/SDK">
    1. Use the [`create_collection`](/reference/api/latest/control-plane/create_collection) operation to create a backup of your pod-based index:

       <CodeGroup>
         ```javascript JavaScript theme={null}
         // Requires Node.js SDK v6.1.2 or later
         import { Pinecone } from '@pinecone-database/pinecone'

         const pc = new Pinecone({
           apiKey: 'YOUR_API_KEY'
         });

         await pc.createCollection({
           name: "pod-collection",
           source: "pod-index"
         });
         ```

         ```go Go theme={null}
         // Requires Go SDK v4.1.2 or later
         package main

         import (
             "context"
             "fmt"
             "log"

             "github.com/pinecone-io/go-pinecone/v4/pinecone"
         )

         func main() {
             ctx := context.Background()

             pc, err := pinecone.NewClient(pinecone.NewClientParams{
                 ApiKey: "YOUR_API_KEY",
             })
             if err != nil {
                 log.Fatalf("Failed to create Client: %v", err)
             }

             collection, err := pc.CreateCollection(ctx, &pinecone.CreateCollectionRequest{
                 Name: "pod-collection", 
                 Source: "pod-index",
             })
             if err != nil {
                 log.Fatalf("Failed to create collection: %v", err)
             } else {
                 fmt.Printf("Successfully created collection: %v", collection.Name)
             }
         }
         ```

         ```shell curl theme={null}
         PINECONE_API_KEY="YOUR_API_KEY"

         curl -s POST "https://api.pinecone.io/collections" \
         -H "Accept: application/json" \
         -H "Content-Type: application/json" \
         -H "Api-Key: $PINECONE_API_KEY" \
         -H "X-Pinecone-Api-Version: 2025-10" \
         -d '{
                 "name": "pod-collection",
                 "source": "pod-index"
         }'
         ```
       </CodeGroup>

    2. Use the [`create_index`](/reference/api/latest/control-plane/create_index) operation to create a new serverless index from the collection:

       * Use API verison `2025-04` or later. Creating a serverless index from a collection is not supported in earlier versions.
       * Set `dimension` to the same dimension as the pod-based index. Changing the dimension is not supported.
       * Set `cloud` to the cloud where the pod-based index is hosted. Migrating to a different cloud is not supported.
       * Set `source_collection` to the name of the collection you created in step 1.

       <CodeGroup>
         ```javascript JavaScript theme={null}
         import { Pinecone } from '@pinecone-database/pinecone'

         const pc = new Pinecone({
           apiKey: 'YOUR_API_KEY'
         });

         await pc.createIndex({
           name: 'serverless-index',
           vectorType: 'dense',
           dimension: 1536,
           metric: 'cosine',
           spec: {
             serverless: {
               cloud: 'aws',
               region: 'us-east-1',
               sourceCollection: 'pod-collection'
             }
           }
         });
         ```

         ```go Go theme={null}
         package main

         import (
             "context"
             "fmt"
             "log"

             "github.com/pinecone-io/go-pinecone/v4/pinecone"
         )

         func main() {
             ctx := context.Background()

             pc, err := pinecone.NewClient(pinecone.NewClientParams{
                 ApiKey: "YOUR_API_KEY",
             })
             if err != nil {
                 log.Fatalf("Failed to create Client: %v", err)
             }

             idx, err := pc.CreateServerlessIndex(ctx, &pinecone.CreateServerlessIndexRequest{
                 Name:      "serverless-index",
                 VectorType: "dense",
                 Dimension: 1536,
                 Metric:    pinecone.Cosine,
                 Cloud:     pinecone.Aws,
                 Region:    "us-east-1",
                 SourceCollection: "pod-collection",
             })
             if err != nil {
                 log.Fatalf("Failed to create serverless index: %v", err)
             } else {
                 fmt.Printf("Successfully created serverless index: %v", idx.Name)
             }
         }
         ```

         ```shell curl theme={null}
         PINECONE_API_KEY="YOUR_API_KEY"

         curl -s "https://api.pinecone.io/indexes" \
         -H "Accept: application/json" \
         -H "Content-Type: application/json" \
         -H "Api-Key: $PINECONE_API_KEY" \
         -H "X-Pinecone-Api-Version: 2025-10" \
         -d '{
                 "name": "serverless-index",
                 "vector_type": "dense",
                 "dimension": 1536,
                 "metric": "cosine",
                 "spec": {
                     "serverless": {
                         "cloud": "aws",
                         "region": "us-east-1",
                         "source_collection": "pod-collection"
                     }
                 }
             }'
         ```
       </CodeGroup>
  </Tab>
</Tabs>

## 4. Update SDKs

If you are using an older version of the Python, Node.js, Java, or Go SDK, you must update the SDK to work with serverless indexes.

1. Check your SDK version:

   <CodeGroup>
     ```shell Python theme={null}
     pip show pinecone  
     ```

     ```shell JavaScript theme={null}
     npm list | grep @pinecone-database/pinecone  
     ```

     ```shell Java  theme={null}
     # Check your dependency file or classpath
     ```

     ```shell Go theme={null}
     go list -u -m all | grep go-pinecone
     ```
   </CodeGroup>

2. If your SDK version is less than 3.0.0 for [Python](https://github.com/pinecone-io/pinecone-python-client), 2.0.0 for [Node.js](https://sdk.pinecone.io/typescript/), 1.0.0 for [Java](https://github.com/pinecone-io/pinecone-java-client), or 1.0.0 for [Go](https://github.com/pinecone-io/go-pinecone), upgrade the SDK as follows:

   <CodeGroup>
     ```Python Python theme={null}
     pip install "pinecone[grpc]" --upgrade  
     ```

     ```JavaScript JavaScript theme={null}
     npm install @pinecone-database/pinecone@latest  
     ```

     ```shell Java theme={null}
     # Maven
     <dependency>
       <groupId>io.pinecone</groupId>
       <artifactId>pinecone-client</artifactId>
       <version>5.0.0</version>
     </dependency>

     # Gradle
     implementation "io.pinecone:pinecone-client:5.0.0"
     ```

     ```go Go theme={null}
     go get -u github.com/pinecone-io/go-pinecone/v4/pinecone@latest
     ```
   </CodeGroup>

## 5. Adapt existing code

You must make some minor code changes to work with serverless indexes.

<Warning>
  Serverless indexes do not support some features, as outlined in [Limitations](#limitations). If you were relying on these features for your pod-based index, you’ll need to adapt your code.
</Warning>

1. Change how you import the Pinecone library and authenticate and initialize the client:

   <CodeGroup>
     ```Python Python theme={null}
     from pinecone.grpc import PineconeGRPC as Pinecone
     from pinecone import ServerlessSpec, PodSpec  
     # ServerlessSpec and PodSpec are required only when  
     # creating serverless and pod-based indexes.  
     pc = Pinecone(api_key="YOUR_API_KEY")  
     ```

     ```JavaScript JavaScript theme={null}
     import { Pinecone } from '@pinecone-database/pinecone';  

     const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' });
     ```

     ```java Java theme={null}
     import io.pinecone.clients.Pinecone;
     import org.openapitools.db_control.client.model.*;

     public class InitializeClientExample {
         public static void main(String[] args) {
             Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build();
         }
     }
     ```

     ```go Go theme={null}
     package main

     import (
         "context"
         "log"

         "github.com/pinecone-io/go-pinecone/v4/pinecone"
     )

     func main() {
         ctx := context.Background()

         pc, err := pinecone.NewClient(pinecone.NewClientParams{
             ApiKey: "YOUR_API_KEY",
         })
         if err != nil {
             log.Fatalf("Failed to create Client: %v", err)
         }
     }
     ```
   </CodeGroup>

2. [Listing indexes](/guides/manage-data/manage-indexes) now fetches a complete description of each index. If you were relying on the output of this operation, you'll need to adapt your code.

   <CodeGroup>
     ```Python Python theme={null}
     from pinecone.grpc import PineconeGRPC as Pinecone

     pc = Pinecone(api_key="YOUR_API_KEY")

     index_list = pc.list_indexes()

     print(index_list)
     ```

     ```javascript JavaScript theme={null}
     import { Pinecone } from '@pinecone-database/pinecone'

     const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' })

     const indexList = await pc.listIndexes();

     console.log(indexList);
     ```

     ```java Java theme={null}
     import io.pinecone.clients.Pinecone;
     import org.openapitools.db_control.client.model.*;

     public class ListIndexesExample {
         public static void main(String[] args) {
             Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build();
             IndexList indexList = pc.listIndexes();
             System.out.println(indexList);
         }
     }
     ```

     ```go Go theme={null}
     package main

     import (
         "context"
         "encoding/json"
         "fmt"
         "log"

         "github.com/pinecone-io/go-pinecone/v4/pinecone"
     )

     func prettifyStruct(obj interface{}) string {
         bytes, _ := json.MarshalIndent(obj, "", "  ")
         return string(bytes)
     }

     func main() {
         ctx := context.Background()

         pc, err := pinecone.NewClient(pinecone.NewClientParams{
             ApiKey: "YOUR_API_KEY",
         })
         if err != nil {
             log.Fatalf("Failed to create Client: %v", err)
         }

         idxs, err := pc.ListIndexes(ctx)
         if err != nil {
             log.Fatalf("Failed to list indexes: %v", err)
         } else {
             for _, index := range idxs {
                 fmt.Printf("index: %v\n", prettifyStruct(index))
             }
         }
     }
     ```

     ```shell curl theme={null}
     PINECONE_API_KEY="YOUR_API_KEY"

     curl -i -X GET "https://api.pinecone.io/indexes" \
     -H "Api-Key: $PINECONE_API_KEY" \
     -H "X-Pinecone-Api-Version: 2025-10"
     ```
   </CodeGroup>

   The `list_indexes` operation now returns a response like the following:

   <CodeGroup>
     ```python Python theme={null}
     [{
         "name": "docs-example-sparse",
         "metric": "dotproduct",
         "host": "docs-example-sparse-govk0nt.svc.aped-4627-b74a.pinecone.io",
         "spec": {
             "serverless": {
                 "cloud": "aws",
                 "region": "us-east-1"
             }
         },
         "status": {
             "ready": true,
             "state": "Ready"
         },
         "vector_type": "sparse",
         "dimension": null,
         "deletion_protection": "disabled",
         "tags": {
             "environment": "development"
         }
     }, {
         "name": "docs-example-dense",
         "metric": "cosine",
         "host": "docs-example-dense-govk0nt.svc.aped-4627-b74a.pinecone.io",
         "spec": {
             "serverless": {
                 "cloud": "aws",
                 "region": "us-east-1"
             }
         },
         "status": {
             "ready": true,
             "state": "Ready"
         },
         "vector_type": "dense",
         "dimension": 1536,
         "deletion_protection": "disabled",
         "tags": {
             "environment": "development"
         }
     }]
     ```

     ```javascript JavaScript theme={null}
     {
       indexes: [
         {
           name: 'docs-example-sparse',
           dimension: undefined,
           metric: 'dotproduct',
           host: 'docs-example-sparse-govk0nt.svc.aped-4627-b74a.pinecone.io',
           deletionProtection: 'disabled',
           tags: { environment: 'development', example: 'tag' },
           embed: undefined,
           spec: { pod: undefined, serverless: { cloud: 'aws', region: 'us-east-1' } },
           status: { ready: true, state: 'Ready' },
           vectorType: 'sparse'
         },
         {
           name: 'docs-example-dense',
           dimension: 1536,
           metric: 'cosine',
           host: 'docs-example-dense-govk0nt.svc.aped-4627-b74a.pinecone.io',
           deletionProtection: 'disabled',
           tags: { environment: 'development', example: 'tag' },
           embed: undefined,
           spec: { pod: undefined, serverless: { cloud: 'aws', region: 'us-east-1' } },
           status: { ready: true, state: 'Ready' },
           vectorType: 'dense'
         }
       ]
     }
     ```

     ```java Java theme={null}
     class IndexList {
         indexes: [class IndexModel {
             name: docs-example-sparse
             dimension: null
             metric: dotproduct
             host: docs-example-sparse-govk0nt.svc.aped-4627-b74a.pinecone.io
             deletionProtection: disabled
             tags: {environment=development}
             embed: null
             spec: class IndexModelSpec {
                 pod: null
                 serverless: class ServerlessSpec {
                     cloud: aws
                     region: us-east-1
                     additionalProperties: null
                 }
                 additionalProperties: null
             }
             status: class IndexModelStatus {
                 ready: true
                 state: Ready
                 additionalProperties: null
             }
             vectorType: sparse
             additionalProperties: null
         }, class IndexModel {
             name: docs-example-dense
             dimension: 1536
             metric: cosine
             host: docs-example-dense-govk0nt.svc.aped-4627-b74a.pinecone.io
             deletionProtection: disabled
             tags: {environment=development}
             embed: null
             spec: class IndexModelSpec {
                 pod: null
                 serverless: class ServerlessSpec {
                     cloud: aws
                     region: us-east-1
                     additionalProperties: null
                 }
                 additionalProperties: null
             }
             status: class IndexModelStatus {
                 ready: true
                 state: Ready
                 additionalProperties: null
             }
             vectorType: dense
             additionalProperties: null
         }]
         additionalProperties: null
     }
     ```

     ```go Go theme={null}
     index: {
       "name": "docs-example-sparse",
       "host": "docs-example-sparse-govk0nt.svc.aped-4627-b74a.pinecone.io",
       "metric": "dotproduct",
       "vector_type": "sparse",
       "deletion_protection": "disabled",
       "dimension": null,
       "spec": {
         "serverless": {
           "cloud": "aws",
           "region": "us-east-1"
         }
       },
       "status": {
         "ready": true,
         "state": "Ready"
       },
       "tags": {
         "environment": "development"
       }
     }
     index: {
       "name": "docs-example-dense",
       "host": "docs-example-dense-govk0nt.svc.aped-4627-b74a.pinecone.io",
       "metric": "cosine",
       "vector_type": "dense",
       "deletion_protection": "disabled",
       "dimension": 1536,
       "spec": {
         "serverless": {
           "cloud": "aws",
           "region": "us-east-1"
         }
       },
       "status": {
         "ready": true,
         "state": "Ready"
       },
       "tags": {
         "environment": "development"
       }
     }
     ```

     ```json curl theme={null}
     {
       "indexes": [
         {
           "name": "docs-example-sparse",
           "vector_type": "sparse",
           "metric": "dotproduct",
           "dimension": null,
           "status": {
             "ready": true,
             "state": "Ready"
           },
           "host": "docs-example-sparse-govk0nt.svc.aped-4627-b74a.pinecone.io",
           "spec": {
             "serverless": {
               "region": "us-east-1",
               "cloud": "aws"
             }
           },
           "deletion_protection": "disabled",
           "tags": {
             "environment": "development"
           }
         },
         {
           "name": "docs-example-dense",
           "vector_type": "dense",
           "metric": "cosine",
           "dimension": 1536,
           "status": {
             "ready": true,
             "state": "Ready"
           },
           "host": "docs-example-dense-govk0nt.svc.aped-4627-b74a.pinecone.io",
           "spec": {
             "serverless": {
               "region": "us-east-1",
               "cloud": "aws"
             }
           },
           "deletion_protection": "disabled",
           "tags": {
             "environment": "development"
           }
         }
       ]
     }
     ```
   </CodeGroup>

3. [Describing an index](/guides/manage-data/manage-indexes) now returns a description of an index in a different format. It also returns the index host needed to run data plane operations against the index. If you were relying on the output of this operation, you'll need to adapt your code.

   <CodeGroup>
     ```Python Python theme={null}
     from pinecone.grpc import PineconeGRPC as Pinecone

     pc = Pinecone(api_key="YOUR_API_KEY")

     pc.describe_index(name="docs-example")
     ```

     ```JavaScript JavaScript theme={null}
     import { Pinecone } from '@pinecone-database/pinecone';

     const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' });

     await pc.describeIndex('docs-example');
     ```

     ```java Java theme={null}
     import io.pinecone.clients.Pinecone;
     import org.openapitools.db_control.client.model.*;

     public class DescribeIndexExample {
         public static void main(String[] args) {
             Pinecone pc = new Pinecone.Builder("YOURE_API_KEY").build();
             IndexModel indexModel = pc.describeIndex("docs-example");
             System.out.println(indexModel);
         }
     }
     ```

     ```go Go theme={null}
     package main

     import (
         "context"
         "encoding/json"
         "fmt"
         "log"

         "github.com/pinecone-io/go-pinecone/v4/pinecone"
     )

     func prettifyStruct(obj interface{}) string {
         bytes, _ := json.MarshalIndent(obj, "", "  ")
         return string(bytes)
     }

     func main() {
         ctx := context.Background()

         pc, err := pinecone.NewClient(pinecone.NewClientParams{
             ApiKey: "YOUR_API_KEY",
         })
         if err != nil {
             log.Fatalf("Failed to create Client: %v", err)
         }

         idx, err := pc.DescribeIndex(ctx, "docs-example")
         if err != nil {
             log.Fatalf("Failed to describe index \"%v\": %v", idx.Name, err)
         } else {
             fmt.Printf("index: %v\n", prettifyStruct(idx))
         }
     }
     ```

     ```bash curl theme={null}
     PINECONE_API_KEY="YOUR_API_KEY"

     curl -i -X GET "https://api.pinecone.io/indexes/docs-example" \
         -H "Api-Key: $PINECONE_API_KEY" \
         -H "X-Pinecone-Api-Version: 2025-10"
     ```
   </CodeGroup>

## 6. Use your new index

When you're ready to cutover to your new serverless index:

1. Your new serverless index has a different name and unique endpoint than your pod-based index. Update your code to target the new serverless index:

   <CodeGroup>
     ```Python Python theme={null}
     index = pc.Index("YOUR_SERVERLESS_INDEX_NAME")  
     ```

     ```JavaScript JavaScript theme={null}
     const index = pc.index("YOUR_SERVERLESS_INDEX_NAME");
     ```

     ```java Java theme={null}
     import io.pinecone.clients.Index;
     import io.pinecone.clients.Pinecone;

     public class TargetIndexExample {
         public static void main(String[] args) {
             Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build();
             Index index = pc.getIndexConnection("YOUR_SERVERLESS_INDEX_NAME");
     ```

     ```go Go theme={null}
     package main

     import (
         "context"
         "log"

         "github.com/pinecone-io/go-pinecone/v4/pinecone"
     )

     func main() {

         ctx := context.Background()

         pc, err := pinecone.NewClient(pinecone.NewClientParams{
             ApiKey: "YOUR_API_KEY",
         })
         if err != nil {
             log.Fatalf("Failed to create Client: %v", err)
         }

         idx, err := pc.DescribeIndex(ctx, "YOUR_SERVERLESS_INDEX_NAME")
         if err != nil {
             log.Fatalf("Failed to describe index \"%v\": %v", idx.Name, err)
         }

         idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: idx.Host, Namespace: "example-namespace"})
         if err != nil {
             log.Fatalf("Failed to create IndexConnection for Host %v: %v", idx.Host, err)
         }
     }
     ```

     ```bash curl theme={null}
     # When using the API directly, you need the unique endpoint for your new serverless index. 
     # See https://docs.pinecone.io/guides/manage-data/target-an-index for details.
     PINECONE_API_KEY="YOUR_API_KEY"
     INDEX_HOST="INDEX_HOST"

     curl -X POST "https://$INDEX_HOST/describe_index_stats" \  
         -H "Api-Key: $PINECONE_API_KEY" \
         -H "X-Pinecone-Api-Version: 2025-10" 
     ```
   </CodeGroup>

2. Reinitialize your clients.

3. If you logged writes to the pod-based index during migration, replay the logged writes to your serverless index.

4. [Delete the pod-based index](/guides/manage-data/manage-indexes#delete-an-index) to avoid paying for unused resources.

   <Warning>
     It is not possible to save a serverless index as a collection, so if you want to retain the option to recreate your pod-based index, be sure to keep the collection you created earlier.
   </Warning>

## See also

* [Limits](/reference/api/database-limits)
* [Serverless architecture](/guides/get-started/database-architecture)
* [Understanding serverless cost](/guides/manage-cost/understanding-cost)


# Restore a pod-based index
Source: https://docs.pinecone.io/guides/indexes/pods/restore-a-pod-based-index

Legacy guide for restoring Pinecone pod-based indexes from collections. Pod indexes are no longer available to new customers as of August 2025.

<Warning>
  Customers who sign up for a Standard or Enterprise plan on or after August 18, 2025 cannot create pod-based indexes. Instead, create [serverless indexes](/guides/index-data/create-an-index), and consider using [dedicated read nodes](/guides/index-data/dedicated-read-nodes) for large workloads (millions of records or more, and moderate or high query rates).
</Warning>

You can restore a pod-based index by creating a new index from a [collection](/guides/indexes/pods/understanding-collections).

## Create a pod-based index from a collection

To create a pod-based index from a [collection](/guides/manage-data/back-up-an-index#pod-based-index-backups-using-collections), use the [`create_index`](/reference/api/latest/control-plane/create_index) endpoint and provide a [`source_collection`](/reference/api/latest/control-plane/create_index#!path=source%5Fcollection\&t=request) parameter containing the name of the collection from which you wish to create an index. The new index can differ from the original source index: the new index can have a different name, number of pods, or pod type. The new index is queryable and writable.

<CodeGroup>
  ```Python Python theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone, PodSpec

  pc = Pinecone(api_key="YOUR_API_KEY")

  pc.create_index(
    name="docs-example",
    dimension=128,
    metric="cosine",
    spec=PodSpec(
      environment="us-west-1-gcp",
      pod_type="p1.x1",
      pods=1,
      source_collection="example-collection"
    )
  )
  ```

  ```JavaScript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone'

  const pc = new Pinecone({
    apiKey: 'YOUR_API_KEY'
  });

  await pc.createIndex({
    name: 'docs-example',
    dimension: 128,
    metric: 'cosine',
    spec: {
      pod: {
        environment: 'us-west-1-gcp',
        podType: 'p1.x1',
        pods: 1,
        sourceCollection: 'example-collection'
      }
    }
  });
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Pinecone;
  import org.openapitools.db_control.client.model.IndexModel;
  import org.openapitools.db_control.client.model.DeletionProtection;

  public class CreateIndexFromCollectionExample {
      public static void main(String[] args) {
          Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build();
          pc.createPodsIndex("docs-example", 1536, "us-west1-gcp",
                  "p1.x1", "cosine", "example-collection", DeletionProtection.DISABLED);
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "fmt"
      "log"

      "github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

      indexName := "docs-example"
      metric := pinecone.Dotproduct
      deletionProtection := pinecone.DeletionProtectionDisabled

      idx, err := pc.CreatePodIndex(ctx, &pinecone.CreatePodIndexRequest{
          Name:               indexName,
          Metric:             &metric,
          Dimension:          1536,
          Environment:        "us-east1-gcp",
          PodType:            "p1.x1",
          SourceCollection:   "example-collection",
          DeletionProtection: &deletionProtection,
      })
      if err != nil {
          log.Fatalf("Failed to create pod-based index: %v", idx.Name)
      } else {
          fmt.Printf("Successfully created pod-based index: %v", idx.Name)
      }
  }
  ```

  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"

  curl -s "https://api.pinecone.io/indexes" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2025-10" \
    -d '{
           "name": "docs-example",
           "dimension": 128,
           "metric": "cosine",
           "spec": {
              "pod": {
                 "environment": "us-west-1-gcp",
                 "pod_type": "p1.x1",
                 "pods": 1,
                 "source_collection": "example-collection"
              }
           }
        }'
  ```
</CodeGroup>


# Scale pod-based indexes
Source: https://docs.pinecone.io/guides/indexes/pods/scale-pod-based-indexes

Scale Pinecone pod-based indexes by adding pods or replicas. Legacy guide: pod indexes are unavailable to new customers; serverless scales automatically.

<Warning>
  Customers who sign up for a Standard or Enterprise plan on or after August 18, 2025 cannot create pod-based indexes. Instead, create [serverless indexes](/guides/index-data/create-an-index), and consider using [dedicated read nodes](/guides/index-data/dedicated-read-nodes) for large workloads (millions of records or more, and moderate or high query rates).
</Warning>

While your index can still serve queries, new upserts may fail as the capacity becomes exhausted. If you need to scale your environment to accommodate more vectors, you can modify your existing index and scale it vertically or create a new index and scale horizontally.

This page explains how you can scale your [pod-based indexes](/guides/index-data/indexing-overview#pod-based-indexes) horizontally and vertically.

## Vertical vs. horizontal scaling

If you need to scale your environment to accommodate more vectors, you can modify your existing index to scale it vertically or create a new index and scale horizontally. This article will describe both methods and how to scale your index effectively.

## Vertical scaling

[Vertical scaling](https://www.pinecone.io/learn/testing-p2-collections-scaling/#vertical-scaling-on-p1-and-s1) is fast and involves no downtime. This is a good choice when you can't pause upserts and must continue serving traffic. It also allows you to double your capacity instantly. However, there are some factors to consider.

### Increase pod size

The default [pod size](/guides/index-data/indexing-overview#pod-size-and-performance) is `x1`. You can increase the size to `x2`, `x4`, or `x8`. Moving up to the next size effectively doubles the capacity of the index. If you need to scale by smaller increments, then consider horizontal scaling.

Increasing the pod size of your index does not result in downtime. Reads and writes continue uninterrupted during the scaling process, which completes in about 10 minutes. You cannot reduce the pod size of your indexes.

The number of base pods you specify when you initially create the index is static and cannot be changed. For example, if you start with 10 pods of `p1.x1` and vertically scale to `p1.x2`, this equates to 20 pods worth of usage. Pod types (performance versus storage pods) also cannot be changed with vertical scaling. If you want to change your pod type while scaling, then horizontal scaling is the better option.

#### When to increase pod size

If your index is at around 90% fullness, we recommend increasing its size. This helps ensure optimal performance and prevents upserts from failing due to capacity constraints.

#### How to increase pod size

You can increase the pod size in the Pinecone console or using the API.

<Tabs>
  <Tab title="Console">
    1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects).
    2. Select the project containing the index you want to configure.
    3. Go to **Database > Indexes**.
    4. Select the index.
    5. Click the **...** button.
    6. Select **Configure**.
    7. In the dropdown, choose the pod size to use.
    8. Click **Confirm**.
  </Tab>

  <Tab title="API">
    Use the [`configure_index`](/reference/api/latest/control-plane/configure_index) operation and append the new size to the `pod_type` parameter, separated by a period (.).

    **Example**

    The following example assumes that `docs-example` has size `x1` and increases the size to `x2`.

    <CodeGroup>
      ```Python Python theme={null}
      from pinecone.grpc import PineconeGRPC as Pinecone

      pc = Pinecone(api_key="YOUR_API_KEY")

      pc.configure_index("docs-example", pod_type="s1.x2")
      ```

      ```JavaScript JavaScript theme={null}
      import { Pinecone } from '@pinecone-database/pinecone'

      const pinecone = new Pinecone({
        apiKey: 'YOUR_API_KEY'
      });

      await pc.configureIndex('docs-example', {
        spec: {
          pod: {
            podType: 's1.x2',
          },
        },
      });
      ```

      ```java Java theme={null}
      import io.pinecone.clients.Pinecone;

      public class ConfigureIndexExample {
          public static void main(String[] args) {
              Pinecone pc = new Pinecone.Builder("PINECONE_API_KEY").build();
              pc.configurePodsIndex("docs-example", "s1.x2");
          }
      }
      ```

      ```go Go theme={null}
      package main

      import (
          "context"
          "fmt"
          "log"

          "github.com/pinecone-io/go-pinecone/v4/pinecone"
      )

      func main() {
          ctx := context.Background()

          pc, err := pinecone.NewClient(pinecone.NewClientParams{
              ApiKey: "YOUR_API_KEY",
          })
          if err != nil {
              log.Fatalf("Failed to create Client: %v", err)
          }

          idx, err := pc.ConfigureIndex(ctx, "docs-example", pinecone.ConfigureIndexParams{PodType: "s1.x2"})
        	if err != nil {
              log.Fatalf("Failed to configure index \"%v\": %v", idx.Name, err)
          } else {
              fmt.Printf("Successfully configured index \"%v\"", idx.Name)
          }
      }
      ```

      ```bash curl theme={null}
      PINECONE_API_KEY="YOUR_API_KEY"

      curl -s -X PATCH "https://api.pinecone.io/indexes/docs-example-curl" \
        -H "Content-Type: application/json" \
        -H "Api-Key: $PINECONE_API_KEY" \
        -H "X-Pinecone-Api-Version: 2025-10" \
        -d '{
               "pod_type": "s1.x2"
            }'
      ```
    </CodeGroup>
  </Tab>
</Tabs>

<Note>
  The size change can take up to 15 minutes to complete.
</Note>

### Decrease pod size

After creating an index, you cannot vertically downscale the index/pod size. Instead, you must [create a collection](/guides/indexes/pods/back-up-a-pod-based-index) and then [create a new index from your collection](/guides/indexes/pods/restore-a-pod-based-index) and specify your desired pod size.

### Check the status of a pod size change

To check the status of a pod size change, use the [`describe_index`](/reference/api/latest/control-plane/describe_index/) endpoint. The `status` field in the results contains the key-value pair `"state":"ScalingUp"` or `"state":"ScalingDown"` during the resizing process and the key-value pair `"state":"Ready"` after the process is complete.

The index fullness metric provided by [`describe_index_stats`](/reference/api/latest/data-plane/describeindexstats) may be inaccurate until the resizing process is complete.

**Example**

The following example uses `describe_index` to get the index status of the index `docs-example`. The `status` field contains the key-value pair `"state":"ScalingUp"`, indicating that the resizing process is still ongoing.

<CodeGroup>
  ```Python Python theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")

  pc.describe_index(name="docs-example")
  ```

  ```JavaScript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone'

  const pc = new Pinecone({
    apiKey: 'YOUR_API_KEY'
  });

  await pc.describeIndex({
    name: "docs-example",
  });
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Pinecone;
  import org.openapitools.db_control.client.model.*;

  public class DescribeIndexExample {
      public static void main(String[] args) {
          Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build();
          IndexModel indexModel = pc.describeIndex("docs-example");
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "fmt"
      "log"

      "github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

      idx, err := pc.DescribeIndex(ctx, "docs-example")
    	if err != nil {
          log.Fatalf("Failed to describe index %v: %v", idx.Name, err)
      } else {
          fmt.Printf("Successfully found index: %v", idx.Name)
      }
  }
  ```

  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"

  curl -s -X GET "https://api.pinecone.io/indexes/docs-example-curl" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2025-10"
  ```
</CodeGroup>

## Horizontal scaling

There are two approaches to horizontal scaling in Pinecone: adding pods and adding replicas. Adding pods increases all resources but requires a pause in upserts; adding replicas only increases throughput and requires no pause in upserts.

### Add pods

Adding additional pods to a running index is not supported directly. However, you can increase the number of pods by using our [collections](/guides/indexes/pods/understanding-collections) feature to create a new index with more pods.

A collection is an immutable snapshot of your index in time: a collection stores the data but not the original index configuration. When you [create an index from a collection](/guides/indexes/pods/create-a-pod-based-index#create-a-pod-index-from-a-collection), you define the new index configuration. This allows you to scale the base pod count horizontally without scaling vertically.

The main advantage of this approach is that you can scale incrementally instead of doubling capacity as with vertical scaling. Also, you can redefine pod types if you are experimenting or if you need to use a different pod type, such as performance-optimized pods or storage-optimized pods. Another advantage of this method is that you can change your [metadata configuration](/guides/indexes/pods/manage-pod-based-indexes#selective-metadata-indexing) to redefine metadata fields as indexed or stored-only. This is important when tuning your index for the best throughput.

Here are the general steps to make a copy of your index and create a new index while changing the pod type, pod count, metadata configuration, replicas, and all typical parameters when creating a new collection:

1. Pause upserts.
2. Create a collection from the current index.
3. Create an index from the collection with new parameters.
4. Continue upserts to the newly created index. Note: the URL has likely changed.
5. Delete the old index if desired.

For detailed steps on creating the collection, see [backup indexes](/guides/manage-data/back-up-an-index#create-a-backup-using-a-collection). For steps on creating an index from a collection, see [Create an index from a collection](/guides/indexes/pods/create-a-pod-based-index#create-a-pod-index-from-a-collection).

### Add replicas

Each replica duplicates the resources and data in an index. This means that adding additional replicas increases the throughput of the index but not its capacity. However, adding replicas does not require downtime.

Throughput in terms of queries per second (QPS) scales linearly with the number of replicas per index.

#### When to add replicas

There are two primary scenarios where adding replicas is beneficial:

**Increase QPS**: The primary reason to add replicas is to increase your index's queries per second (QPS). Each new replica adds another pod for reading from your index and, generally speaking, will increase your QPS by an equal amount as a single pod. For example, if you consistently get 25 QPS for a single pod, each replica will result in 25 more QPS.

If you don't see an increase in QPS after adding replicas, add multiprocessing to your application to ensure you are running parallel operations. You can use the [Pinecone gRPC SDK](/guides/index-data/upsert-data#grpc-python-sdk), or your multiprocessing library of choice.

**Provide data redundancy**: When you add a replica to your index, the Pinecone controller will choose a zone in the same region that does not currently have a replica, up to a maximum of three zones (your fourth and subsequent replicas will be hosted in zones with existing replicas). If your application requires multizone redundancy, this is our recommended approach to achieve that.

#### How to add replicas

To add replicas, use the `configure_index` endpoint to increase the number of replicas for your index:

<CodeGroup>
  ```Python Python theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")

  pc.configure_index("docs-example", replicas=4)
  ```

  ```JavaScript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone'

  const pc = new Pinecone({
    apiKey: 'YOUR_API_KEY'
  });

  await pc.configureIndex('docs-example', {
    spec: {
      pod: {
        replicas: 4,
      },
    },
  });
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Pinecone;

  public class ConfigureIndexExample {
      public static void main(String[] args) {
          Pinecone pc = new Pinecone.Builder("PINECONE_API_KEY").build();
          pc.configurePodsIndex("docs-example", 4, DeletionProtection.DISABLED);
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "fmt"
      "log"

      "github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

      idx, err := pc.ConfigureIndex(ctx, "docs-example", pinecone.ConfigureIndexParams{Replicas: 4})
    	if err != nil {
          log.Fatalf("Failed to configure index \"%v\": %v", idx.Name, err)
      } else {
          fmt.Printf("Successfully configured index \"%v\"", idx.Name)
      }
  }
  ```

  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"

  curl -s -X PATCH "https://api.pinecone.io/indexes/docs-example-curl" \
    -H "Content-Type: application/json" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2025-10" \
    -d '{
           "replicas": 4
        }'
  ```
</CodeGroup>

## Next steps

* See our learning center for more information on [vertical scaling](https://www.pinecone.io/learn/testing-p2-collections-scaling/#vertical-scaling-on-p1-and-s1).
* Learn more about [collections](/guides/indexes/pods/understanding-collections).


# Understanding collections
Source: https://docs.pinecone.io/guides/indexes/pods/understanding-collections

Legacy documentation for Pinecone collections, a pod-only feature for creating static index snapshots. Collections are not available for serverless indexes.

<Warning>
  Customers who sign up for a Standard or Enterprise plan on or after August 18, 2025 cannot create pod-based indexes. Instead, create [serverless indexes](/guides/index-data/create-an-index), and consider using [dedicated read nodes](/guides/index-data/dedicated-read-nodes) for large workloads (millions of records or more, and moderate or high query rates).
</Warning>

A collection is a static copy of a pod-based index that only consumes storage. It is a non-queryable representation of a set of records. You can [create a collection](/guides/indexes/pods/back-up-a-pod-based-index) of a pod-based index, and you can [create a new pod-based index from a collection](/guides/manage-data/restore-an-index). This allows you to restore the index with the same or different configurations.

<Note>
  Once a collection is created, it cannot be moved to a different project.
</Note>

## Use cases

Creating a collection is useful when performing tasks like the following:

* Protecting an index from manual or system failures.
* Temporarily shutting down an index.
* Copying the data from one index into a different index.
* Making a backup of your index.
* Experimenting with different index configurations.

## Performance

Collections operations perform differently, depending on the pod type of the index:

* Creating a `p1` or `s1` index from a collection takes approximately 10 minutes.
* Creating a `p2` index from a collection can take several hours when the number of vectors is on the order of 1,000,000.

## Limitations

Collection limitations are as follows:

* You can only perform operations on collections in the current Pinecone project.

## Pricing

See [Pricing](https://www.pinecone.io/pricing/) for up-to-date pricing information.


# Understanding pod-based indexes
Source: https://docs.pinecone.io/guides/indexes/pods/understanding-pod-based-indexes

Understand Pinecone pod-based indexes, including pod types and sizing. Legacy: pod indexes are unavailable to new customers; use serverless for new projects.

<Warning>
  Customers who sign up for a Standard or Enterprise plan on or after August 18, 2025 cannot create pod-based indexes. Instead, create [serverless indexes](/guides/index-data/create-an-index), and consider using [dedicated read nodes](/guides/index-data/dedicated-read-nodes) for large workloads (millions of records or more, and moderate or high query rates).
</Warning>

With pod-based indexes, you choose one or more pre-configured units of hardware (pods). Depending on the pod type, pod size, and number of pods used, you get different amounts of storage and higher or lower latency and throughput. Be sure to [choose an appropriate pod type and size](/guides/indexes/pods/choose-a-pod-type-and-size) for your dataset and workload.

## Pod types

Different pod types are priced differently. See [Understanding cost](/guides/manage-cost/understanding-cost) for more details.

<Note>
  Once a pod-based index is created, you cannot change its pod type. However, you can create a collection from an index and then [create a new index with a different pod type](/guides/indexes/pods/create-a-pod-based-index#create-a-pod-index-from-a-collection) from the collection.
</Note>

### s1 pods

These storage-optimized pods provide large storage capacity and lower overall costs with slightly higher query latencies than p1 pods. They are ideal for very large indexes with moderate or relaxed latency requirements.

Each s1 pod has enough capacity for around 5M vectors of 768 dimensions.

### p1 pods

These performance-optimized pods provide very low query latencies, but hold fewer vectors per pod than s1 pods. They are ideal for applications with low latency requirements (\<100ms).

Each p1 pod has enough capacity for around 1M vectors of 768 dimensions.

### p2 pods

The p2 pod type provides greater query throughput with lower latency. For vectors with fewer than 128 dimension and queries where `topK` is less than 50, p2 pods support up to 200 QPS per replica and return queries in less than 10ms. This means that query throughput and latency are better than s1 and p1.

Each p2 pod has enough capacity for around 1M vectors of 768 dimensions. However, capacity may vary with dimensionality.

The data ingestion rate for p2 pods is significantly slower than for p1 pods; this rate decreases as the number of dimensions increases. For example, a p2 pod containing vectors with 128 dimensions can upsert up to 300 updates per second; a p2 pod containing vectors with 768 dimensions or more supports upsert of 50 updates per second. Because query latency and throughput for p2 pods vary from p1 pods, test p2 pod performance with your dataset.

The p2 pod type does not support sparse vector values.

## Pod size and performance

Each pod type supports four pod sizes: `x1`, `x2`, `x4`, and `x8`. Your index storage and compute capacity doubles for each size step. The default pod size is `x1`. You can increase the size of a pod after index creation.

To learn about changing the pod size of an index, see [Configure an index](/guides/indexes/pods/scale-pod-based-indexes#increase-pod-size).

## Pod environments

When creating a pod-based index, you must choose the cloud environment where you want the index to be hosted. The project environment can affect your [pricing](https://pinecone.io/pricing). The following table lists the available cloud regions and the corresponding values of the `environment` parameter for the [`create_index`](/guides/index-data/create-an-index#create-a-pod-based-index) endpoint:

| Cloud | Region                       | Environment                   |
| ----- | ---------------------------- | ----------------------------- |
| GCP   | us-west-1 (N. California)    | `us-west1-gcp`                |
| GCP   | us-central-1 (Iowa)          | `us-central1-gcp`             |
| GCP   | us-west-4 (Las Vegas)        | `us-west4-gcp`                |
| GCP   | us-east-4 (Virginia)         | `us-east4-gcp`                |
| GCP   | northamerica-northeast-1     | `northamerica-northeast1-gcp` |
| GCP   | asia-northeast-1 (Japan)     | `asia-northeast1-gcp`         |
| GCP   | asia-southeast-1 (Singapore) | `asia-southeast1-gcp`         |
| GCP   | us-east-1 (South Carolina)   | `us-east1-gcp`                |
| GCP   | eu-west-1 (Belgium)          | `eu-west1-gcp`                |
| GCP   | eu-west-4 (Netherlands)      | `eu-west4-gcp`                |
| AWS   | us-east-1 (Virginia)         | `us-east-1-aws`               |
| Azure | eastus (Virginia)            | `eastus-azure`                |

[Contact us](http://www.pinecone.io/contact/) if you need a dedicated deployment in other regions.

The environment cannot be changed after the index is created.

## Pod costs

For each pod-based index, billing is determined by the per-minute price per pod and the number of pods the index uses, regardless of index activity. The per-minute price varies by pod type, pod size, account plan, and cloud region. For the latest pod-based index pricing rates, see [Pricing](https://www.pinecone.io/pricing/pods).

Total cost depends on a combination of factors:

* **Pod type.** Each pod type has different per-minute pricing.
* **Number of pods.** This includes replicas, which duplicate pods.
* **Pod size.**  Larger pod sizes have proportionally higher costs per minute.
* **Total pod-minutes.** This includes the total time each pod is running, starting at pod creation and rounded up to 15-minute increments.
* **Cloud provider.** The cost per pod-type and pod-minute varies depending on the cloud provider you choose for your project.
* **Collection storage.** Collections incur costs per GB of data per minute in storage, rounded up to 15-minute increments.
* **Plan.** The free plan incurs no costs; the Standard or Enterprise plans incur different costs per pod-type, pod-minute, cloud provider, and collection storage.

The following equation calculates the total costs accrued over time:

```
(Number of pods) * (pod size) * (number of replicas) * (minutes pod exists) * (pod price per minute) 
+ (collection storage in GB) * (collection storage time in minutes) * (collection storage price per GB per minute)
```

To see a calculation of your current usage and costs, go to [**Settings > Usage**](https://app.pinecone.io/organizations/-/settings/usage) in the Pinecone console.

<Accordion title="Example">
  While our pricing page lists rates on an hourly basis for ease of comparison, this example lists prices per minute, as this is how Pinecone calculates billing.

  An example application has the following requirements:

  * 1,000,000 vectors with 1536 dimensions
  * 150 queries per second with `top_k` = 10
  * Deployment in an EU region
  * Ability to store 1GB of inactive vectors

  [Based on these requirements](/guides/indexes/pods/choose-a-pod-type-and-size), the organization chooses to configure the project to use the Standard billing plan to host one `p1.x2` pod with three replicas and a collection containing 1 GB of data. This project runs continuously for the month of January on the Standard plan. The components of the total cost for this example are given in Table 1 below:

  **Table 1: Example billing components**

  | Billing component             | Value        |
  | ----------------------------- | ------------ |
  | Number of pods                | 1            |
  | Number of replicas            | 3            |
  | Pod size                      | x2           |
  | Total pod count               | 6            |
  | Minutes in January            | 44,640       |
  | Pod-minutes (pods \* minutes) | 267,840      |
  | Pod price per minute          | \$0.0012     |
  | Collection storage            | 1 GB         |
  | Collection storage minutes    | 44,640       |
  | Price per storage minute      | \$0.00000056 |

  The invoice for this example is given in Table 2 below:

  **Table 2: Example invoice**

  | Product       | Quantity | Price per unit | Charge   |
  | ------------- | -------- | -------------- | -------- |
  | Collections   | 44,640   | \$0.00000056   | \$0.025  |
  | P2 Pods (AWS) | 0        |                | \$0.00   |
  | P2 Pods (GCP) | 0        |                | \$0.00   |
  | S1 Pods       | 0        |                | \$0.00   |
  | P1 Pods       | 267,840  | \$0.0012       | \$514.29 |

  Amount due \$514.54
</Accordion>

## Known limitations

* [Pod storage capacity](#pod-types)
  * Each **p1** pod has enough capacity for 1M vectors with 768 dimensions.
  * Each **s1** pod has enough capacity for 5M vectors with 768 dimensions.
* [Metadata](/guides/index-data/indexing-overview#metadata)
  * Metadata with high cardinality, such as a unique value for every vector in a large index, uses more memory than expected and can cause the pods to become full.
* [Collections](/guides/manage-data/back-up-an-index#pod-based-index-backups-using-collections)
  * You cannot query or write to a collection after its creation. For this reason, a collection only incurs storage costs.
  * You can only perform operations on collections in the current Pinecone project.
* [Sparse-dense vectors](/guides/search/hybrid-search#use-a-single-index-for-dense-and-sparse-vectors)
  * Only `s1` and `p1` [pod-based indexes](/guides/indexes/pods/understanding-pod-based-indexes#pod-types) using the dotproduct distance metric support sparse-dense vectors.


# Manage cost
Source: https://docs.pinecone.io/guides/manage-cost/manage-cost

Reduce Pinecone spend with strategies like spend alerts, ID-prefix listing, multitenant namespaces, prepaid credits, and support cost optimization help.

For the latest pricing details, see our [pricing page](https://www.pinecone.io/pricing/).

For help estimating total cost, see [Understanding cost](/guides/manage-cost/understanding-cost). To view or download a detailed report of your current usage and costs, see [Monitor usage and costs](/guides/manage-cost/monitor-usage-and-costs#monitor-organization-level-usage).

To lower your bill, see [Ways to reduce cost](/guides/manage-cost/understanding-cost#ways-to-reduce-cost) and [Save on costs](/guides/optimize/save-on-costs), which cover available credits and discounts plus ways to optimize your workload.

## Set monthly spend alerts

You can set up email alerts to monitor your organization's monthly spending. These alerts notify designated recipients when spending reaches specified thresholds. The alerts automatically reset at the start of each monthly billing cycle.

<Note>
  Spend alerts are available on the [Standard and Enterprise plans](https://www.pinecone.io/pricing/). They are not needed on the Starter or Builder plans, where usage is capped by plan quotas rather than billed per unit.
</Note>

To set a spend alert:

1. Go to [Settings > Spend alerts](https://app.pinecone.io/organizations/-/settings/spend-alerts) in the Pinecone console
2. Click **+ Add Alert**.
3. Enter the dollar amount for the spend alert.
4. Enter the email addresses to send the alert to. [Organization owners](/guides/organizations/understanding-organizations#organization-roles) are listed by default.
5. Click **Create**.

To edit a spend alert:

1. In the row of the spend alert you want to edit, click **ellipsis (...) menu > Edit**.
2. Change the dollar amount and/or email addresses for the spend alert.
3. Click **Update**.

<Note>
  **Auto-spend spike alert**: To protect from unexpected cost increases, Pinecone sends an alert when spending exceeds double your previous month's invoice amount. While the alert threshold is fixed and the alert cannot be deleted, you can modify which email addresses receive the alert and enable or disable the alert notifications.
</Note>

## List by ID prefix

By using a [hierarchical ID schema](/guides/index-data/data-modeling#use-structured-ids), you can retrieve records without performing a query. To do so, you can use [`list`](/reference/api/latest/data-plane/list) to retrieve records by ID prefix, then use `fetch` to retrieve the records you need. This can reduce costs, because [`query` consumes more RUs when scanning a larger namespace](/guides/manage-cost/understanding-cost#query), while [`fetch` consumes a fixed ratio of RUs to records retrieved](/guides/manage-cost/understanding-cost#fetch).

## Use namespaces for multitenancy

If your application requires you to isolate the data of each customer/user, consider [implementing multitenancy with serverless indexes and namespaces](/guides/index-data/implement-multitenancy). With serverless indexes, you pay only for the amount of data stored and operations performed. For queries in particular, the cost is partly based on the total number of records that must be scanned, so using namespaces can significantly reduce query costs.

## Prepaid credits

Pinecone offers an incentive for customers who purchase prepaid credits with an upfront payment. Customers may purchase between \$8,000 and \$25,000 in prepaid credits.

Customers who purchase prepaid credits can unlock additional usage capacity at no extra cost. The available benefits vary based on the selected plan and prepaid amount.

Prepaid credits apply to Pinecone services at List Price. Any usage that exceeds the available prepaid credits will be billed at full List Price.

Customers on Standard and Enterprise pay-as-you-go plans can purchase prepaid credits directly by navigating in the Pinecone console to [Settings > Billing > Plans](https://app.pinecone.io/organizations/-/settings/billing/plans).

<Note>
  Purchasing prepaid credits is not available through cloud marketplace billing. To purchase prepaid credits through a cloud marketplace, contact [ar@pinecone.io](mailto:ar@pinecone.io).
</Note>

## Talk to support

Users on Standard and Enterprise plans can [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) for help in optimizing costs.

## See also

* [Understanding cost](/guides/manage-cost/understanding-cost)
* [Monitor usage and costs](/guides/manage-cost/monitor-usage-and-costs)
* [Save on costs](/guides/optimize/save-on-costs)


# Monitor usage and costs
Source: https://docs.pinecone.io/guides/manage-cost/monitor-usage-and-costs

Monitor Pinecone usage and costs at the organization, index, and operation level by tracking read units, write units, and storage consumption.

## Monitor organization-level usage and costs

<Note>
  To view usage and costs across your Pinecone organization, you must be an [organization owner or billing admin](/guides/organizations/understanding-organizations#organization-roles). Also, this feature is available only to organizations on the Standard or Enterprise plans.
</Note>

The **Usage** dashboard in the Pinecone console gives you a detailed report of usage and costs across your organization, broken down by each billable SKU or aggregated by project or service. You can view the report in the console or download it as a CSV file for more detailed analysis.

1. Go to [**Settings > Usage**](https://app.pinecone.io/organizations/-/settings/usage) in the Pinecone console.
2. Select the time range to report on. This defaults to the last 30 days.
3. Select the scope for your report:
   * **SKU:** The usage and cost for each billable SKU, for example, read units per cloud region, storage size per cloud region, or tokens per embedding model.
   * **Project:** The aggregated cost for each project in your organization.
   * **Service:** The aggregated cost for each service your organization uses, for example, database (includes serverless back up and restore), assistants, inference (embedding and reranking), and collections.
4. Choose the specific SKUs, projects, or services you want to report on. This defaults to all.
5. To download the report as a CSV file, click **Download**.

   <Tip>
     The CSV download provides more granular detail than the console view, including breakdowns by individual index as well as project and index tags.
   </Tip>

Dates are shown in UTC to match billing invoices. Cost data is delayed up to three days from the actual usage date.

## Monitor index-level usage

You can monitor index-level usage directly in the Pinecone console, or you can pull them into [Prometheus](https://prometheus.io/). For more details, see [Monitoring](/guides/production/monitoring).

## Monitor operation-level usage

### Read units

[Query](/guides/search/search-overview), [fetch](/guides/manage-data/fetch-data), and [list by ID](/guides/manage-data/list-record-ids) requests return a `usage` parameter with the [read unit](/guides/manage-cost/understanding-cost#read-units) consumption of each request that is made.

<Warning>
  While Pinecone tracks read unit usage with decimal precision, the Pinecone API and SDKs round these values up to the nearest whole number in query, fetch, and list responses. For example, if a query uses 0.45 read units, the API and SDKs will report it as 1 read unit.

  For precise read unit reporting, see [index-level metrics](/guides/production/monitoring) or the organization-wide [Usage dashboard](/guides/manage-cost/monitor-usage-and-costs#monitor-organization-level-usage-and-costs).
</Warning>

<Note>
  Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide.
</Note>

Example query request:

<CodeGroup>
  ```Python Python theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")
  index = pc.Index("example-index")

  response = index.query(
      vector=[0.22,0.43,0.16,1,...], 
      namespace='example-namespace', 
      top_k=3,
      include_values=False,
      include_metadata=False
  )

  print(response)
  ```

  ```JavaScript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone'

  const pc = new Pinecone({ apiKey: "YOUR_API_KEY" })
  const index = pc.index("example-index")

  const queryResponse = await index.namespace('example-namespace').query({
      vector: [0.22,0.43,0.16,1,...],
      topK: 3,
      includeValues: false,
      includeMetadata: false,
  });

  console.log(queryResponse);
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Index;
  import io.pinecone.configs.PineconeConfig;
  import io.pinecone.configs.PineconeConnection;
  import io.pinecone.unsigned_indices_model.QueryResponseWithUnsignedIndices;

  import java.util.Arrays;
  import java.util.List;

  public class QueryByVector {
      public static void main(String[] args) {
          PineconeConfig config = new PineconeConfig("YOUR_API_KEY");
          // To get the unique host for an index,
          // see https://docs.pinecone.io/guides/manage-data/target-an-index
          config.setHost("INDEX_HOST");
          PineconeConnection connection = new PineconeConnection(config);
          Index index = new Index(config, connection, "example-index");

          List<Float> query = Arrays.asList(0.22f,0.43f,0.16f,1f,...);
          QueryResponseWithUnsignedIndices queryResponse = index.query(3, query, null, null, null, "example-namespace", null, false, false);
          System.out.println(queryResponse);
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
  	"context"
  	"encoding/json"
  	"fmt"
  	"log"

  	"github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func prettifyStruct(obj interface{}) string {
  	bytes, _ := json.MarshalIndent(obj, "", "  ")
  	return string(bytes)
  }

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

  	// To get the unique host for an index,
  	// see https://docs.pinecone.io/guides/manage-data/target-an-index
  	idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST", Namespace: "example-namespace"})
  	if err != nil {
  		log.Fatalf("Failed to create IndexConnection for Host: %v", err)
  	}

  	queryVector := []float32{0.22, 0.43, 0.16, 1, ...}

  	res, err := idxConnection.QueryByVectorValues(ctx, &pinecone.QueryByVectorValuesRequest{
  		Vector:        queryVector,
  		TopK:          3,
  		IncludeValues: false,
  	})
  	if err != nil {
  		log.Fatalf("Error encountered when querying by vector: %v", err)
  	} else {
  		fmt.Printf(prettifyStruct(res))
  	}
  ```
</CodeGroup>

The response looks like this:

<CodeGroup>
  ```python Python theme={null}
  {'matches': [{'id': 'record_193027', 'score': 0.00405937387, 'values': []},
               {'id': 'record_137452', 'score': 0.00405937387, 'values': []},
               {'id': 'record_132264', 'score': 0.00405937387, 'values': []}],
   'namespace': 'example-namespace',
   'usage': {'read_units': 1}}
  ```

  ```javascript JavaScript theme={null}
  {
    matches: [
      {
        id: 'record_186225',
        score: 0.00405937387,
        values: [],
        sparseValues: undefined,
        metadata: undefined
      },
      {
        id: 'record_164994',
        score: 0.00405937387,
        values: [],
        sparseValues: undefined,
        metadata: undefined
      },
      {
        id: 'record_186333',
        score: 0.00405937387,
        values: [],
        sparseValues: undefined,
        metadata: undefined
      }
    ],
    namespace: 'example-namespace',
    usage: { readUnits: 1 }
  }
  ```

  ```java Java theme={null}
  class QueryResponseWithUnsignedIndices {
      matches: [ScoredVectorWithUnsignedIndices {
          score: 0.004059374
          id: record_170370
          values: []
          metadata: 
          sparseValuesWithUnsignedIndices: SparseValuesWithUnsignedIndices {
              indicesWithUnsigned32Int: []
              values: []
          }
      }, ScoredVectorWithUnsignedIndices {
          score: 0.004059374
          id: record_107423
          values: []
          metadata: 
          sparseValuesWithUnsignedIndices: SparseValuesWithUnsignedIndices {
              indicesWithUnsigned32Int: []
              values: []
          }
      }, ScoredVectorWithUnsignedIndices {
          score: 0.004059374
          id: record_171426
          values: []
          metadata: 
          sparseValuesWithUnsignedIndices: SparseValuesWithUnsignedIndices {
              indicesWithUnsigned32Int: []
              values: []
          }
      }]
      namespace: example-index
      usage: read_units: 1
  }
  ```

  ```go Go theme={null}
  {
    "matches": [
      {
        "vector": {
          "id": "record_193027"
        },
        "score": 0.004059374
      },
      {
        "vector": {
          "id": "record_137452"
        },
        "score": 0.004059374
      },
      {
        "vector": {
          "id": "record_132264"
        },
        "score": 0.004059374
      }
    ],
    "usage": {
      "read_units": 1
    },
    "namespace": "example-index"
  }
  ```
</CodeGroup>

For a more in-depth demonstration of how to use read units to inspect read costs, see [this notebook](https://github.com/pinecone-io/examples/blob/master/docs/read-units-demonstrated.ipynb).

### Egress

[Query](/guides/search/search-overview), [fetch](/guides/manage-data/fetch-data), [list](/guides/manage-data/list-record-ids), and [text search](/reference/api/latest/data-plane/search_records) requests return the [egress](/guides/manage-cost/understanding-cost#egress) consumed by each request in the `usage` object, as `egressBytes` (the total bytes returned by the operation, including IDs, scores, values, and metadata).

Egress is reported only on serverless reads that return record data. It is omitted on empty results and on requests that return no record data (such as index statistics and management requests).

### Embedding tokens

Requests to one of [Pinecone's hosted embedding models](/guides/index-data/create-an-index#embedding-models), either directly via the [`embed` operation](/reference/api/latest/inference/generate-embeddings) or automatically when upserting or querying an [index with integrated embedding](/guides/index-data/indexing-overview#integrated-embedding), return a `usage` parameter with the total tokens generated.

For example, the following request to use the `multilingual-e5-large` model to generate embeddings for sentences related to the word “apple” might return this request and summary of embedding tokens generated:

<CodeGroup>
  ```python Python theme={null}
  # Import the Pinecone library
  from pinecone.grpc import PineconeGRPC as Pinecone
  from pinecone import ServerlessSpec
  import time

  # Initialize a Pinecone client with your API key
  pc = Pinecone(api_key="YOUR_API_KEY")

  # Define a sample dataset where each item has a unique ID and piece of text
  data = [
      {"id": "vec1", "text": "Apple is a popular fruit known for its sweetness and crisp texture."},
      {"id": "vec2", "text": "The tech company Apple is known for its innovative products like the iPhone."},
      {"id": "vec3", "text": "Many people enjoy eating apples as a healthy snack."},
      {"id": "vec4", "text": "Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces."},
      {"id": "vec5", "text": "An apple a day keeps the doctor away, as the saying goes."},
      {"id": "vec6", "text": "Apple Computer Company was founded on April 1, 1976, by Steve Jobs, Steve Wozniak, and Ronald Wayne as a partnership."}
  ]

  # Convert the text into numerical vectors that Pinecone can index
  embeddings = pc.inference.embed(
      model="llama-text-embed-v2",
      inputs=[d['text'] for d in data],
      parameters={"input_type": "passage", "truncate": "END"}
  )

  print(embeddings)
  ```

  ```javascript JavaScript theme={null}
  // Import the Pinecone library
  import { Pinecone } from '@pinecone-database/pinecone';

  // Initialize a Pinecone client with your API key
  const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' });

  // Define a sample dataset where each item has a unique ID and piece of text
  const data = [
    { id: 'vec1', text: 'Apple is a popular fruit known for its sweetness and crisp texture.' },
    { id: 'vec2', text: 'The tech company Apple is known for its innovative products like the iPhone.' },
    { id: 'vec3', text: 'Many people enjoy eating apples as a healthy snack.' },
    { id: 'vec4', text: 'Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces.' },
    { id: 'vec5', text: 'An apple a day keeps the doctor away, as the saying goes.' },
    { id: 'vec6', text: 'Apple Computer Company was founded on April 1, 1976, by Steve Jobs, Steve Wozniak, and Ronald Wayne as a partnership.' }
  ];

  // Convert the text into numerical vectors that Pinecone can index
  const model = 'llama-text-embed-v2';

  const embeddings = await pc.inference.embed(
    model,
    data.map(d => d.text),
    { inputType: 'passage', truncate: 'END' }
  );

  console.log(embeddings);
  ```

  ```java Java theme={null}
  // Import the required classes
  import io.pinecone.clients.Index;
  import io.pinecone.clients.Inference;
  import io.pinecone.clients.Pinecone;
  import org.openapitools.inference.client.ApiException;
  import org.openapitools.inference.client.model.Embedding;
  import org.openapitools.inference.client.model.EmbeddingsList;

  import java.math.BigDecimal;
  import java.util.*;
  import java.util.stream.Collectors;

  public class GenerateEmbeddings {
      public static void main(String[] args) throws ApiException {
          // Initialize a Pinecone client with your API key
          Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build();
          Inference inference = pc.getInferenceClient();

          // Prepare input sentences to be embedded
          List<DataObject> data = Arrays.asList(
              new DataObject("vec1", "Apple is a popular fruit known for its sweetness and crisp texture."),
              new DataObject("vec2", "The tech company Apple is known for its innovative products like the iPhone."),
              new DataObject("vec3", "Many people enjoy eating apples as a healthy snack."),
              new DataObject("vec4", "Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces."),
              new DataObject("vec5", "An apple a day keeps the doctor away, as the saying goes."),
              new DataObject("vec6", "Apple Computer Company was founded on April 1, 1976, by Steve Jobs, Steve Wozniak, and Ronald Wayne as a partnership.")
          );

          List<String> inputs = data.stream()
              .map(DataObject::getText)
              .collect(Collectors.toList());

          // Specify the embedding model and parameters
          String embeddingModel = "llama-text-embed-v2";

          Map<String, Object> parameters = new HashMap<>();
          parameters.put("input_type", "passage");
          parameters.put("truncate", "END");

          // Generate embeddings for the input data
          EmbeddingsList embeddings = inference.embed(embeddingModel, parameters, inputs);

          // Get embedded data
          List<Embedding> embeddedData = embeddings.getData();
      }

      private static List<Float> convertBigDecimalToFloat(List<BigDecimal> bigDecimalValues) {
          return bigDecimalValues.stream()
              .map(BigDecimal::floatValue)
              .collect(Collectors.toList());
      }
  }

  class DataObject {
      private String id;
      private String text;

      public DataObject(String id, String text) {
          this.id = id;
          this.text = text;
      }

      public String getId() {
          return id;
      }
      public String getText() {
          return text;
      }
  }
  ```

  ```go Go theme={null}
  package main

  // Import the required packages
  import (
      "context"
     	"encoding/json"
      "fmt"
      "log"

      "github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  type Data struct {
      ID   string
      Text string
  }

  type Query struct {
  	Text string
  }

  func prettifyStruct(obj interface{}) string {
      bytes, _ := json.MarshalIndent(obj, "", "  ")
      return string(bytes)
  }

  func main() {
      ctx := context.Background()

      // Initialize a Pinecone client with your API key
      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

      // Define a sample dataset where each item has a unique ID and piece of text
      data := []Data{
          {ID: "vec1", Text: "Apple is a popular fruit known for its sweetness and crisp texture."},
          {ID: "vec2", Text: "The tech company Apple is known for its innovative products like the iPhone."},
          {ID: "vec3", Text: "Many people enjoy eating apples as a healthy snack."},
          {ID: "vec4", Text: "Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces."},
          {ID: "vec5", Text: "An apple a day keeps the doctor away, as the saying goes."},
          {ID: "vec6", Text: "Apple Computer Company was founded on April 1, 1976, by Steve Jobs, Steve Wozniak, and Ronald Wayne as a partnership."},
      }

      // Specify the embedding model and parameters
      embeddingModel := "llama-text-embed-v2"

      docParameters := pinecone.EmbedParameters{
          InputType: "passage",
          Truncate:  "END",
      }

      // Convert the text into numerical vectors that Pinecone can index
      var documents []string
      for _, d := range data {
          documents = append(documents, d.Text)
      }

      docEmbeddingsResponse, err := pc.Inference.Embed(ctx, &pinecone.EmbedRequest{
          Model:      embeddingModel,
          TextInputs: documents,
          Parameters: docParameters,
      }) 
      if err != nil {
          log.Fatalf("Failed to embed documents: %v", err)
      } else {
          fmt.Printf(prettifyStruct(docEmbeddingsResponse))
      }
  }
  ```

  ```shell curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"

  curl https://api.pinecone.io/embed \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "Content-Type: application/json" \
    -H "X-Pinecone-Api-Version: 2025-10" \
    -d '{
        "model": "llama-text-embed-v2",
        "parameters": {
          "input_type": "passage",
          "truncate": "END"
        },
        "inputs": [
          {"text": "Apple is a popular fruit known for its sweetness and crisp texture."},
          {"text": "The tech company Apple is known for its innovative products like the iPhone."},
          {"text": "Many people enjoy eating apples as a healthy snack."},
          {"text": "Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces."},
          {"text": "An apple a day keeps the doctor away, as the saying goes."},
          {"text": "Apple Computer Company was founded on April 1, 1976, by Steve Jobs, Steve Wozniak, and Ronald Wayne as a partnership."}
        ]
    }'
  ```
</CodeGroup>

The returned object looks like this:

<CodeGroup>
  ```python Python theme={null}
  EmbeddingsList(
      model='llama-text-embed-v2',
      data=[
          {'values': [0.04925537109375, -0.01313018798828125, -0.0112762451171875, ...]},
          ...
      ],
      usage={'total_tokens': 130}
  )
  ```

  ```javascript JavaScript theme={null}
  EmbeddingsList(1) [
    {
      values: [
        0.04925537109375, 
        -0.01313018798828125, 
        -0.0112762451171875,
        ...
      ]
    },
    ...
    model: 'llama-text-embed-v2',
    data: [ { values: [Array] } ],
    usage: { totalTokens: 130 }
  ]
  ```

  ```java Java theme={null}
  class EmbeddingsList {
      model: llama-text-embed-v2
      data: [class Embedding {
          values: [0.04925537109375, -0.01313018798828125, -0.0112762451171875, ...]
          additionalProperties: null
      }, ...]
      usage: class EmbeddingsListUsage {
          totalTokens: 130
          additionalProperties: null
      }
      additionalProperties: null
  }
  ```

  ```go Go theme={null}
  {
    "data": [
      {
        "values": [
          0.03942871,
          -0.010177612,
          -0.046051025,
          ...
        ]
      },
      ...
    ], 
    "model": "llama-text-embed-v2",
    "usage": {
      "total_tokens": 130
    }
  }
  ```

  ```json curl theme={null}
  {
    "data": [
      {
        "values": [
          0.04925537109375,
          -0.01313018798828125,
          -0.0112762451171875,
          ...
        ]
      }, 
      ...
    ],
    "model": "llama-text-embed-v2",
    "usage": {
      "total_tokens": 130
    }
  }
  ```
</CodeGroup>

## See also

* [Understanding cost](/guides/manage-cost/understanding-cost)
* [Manage cost](/guides/manage-cost/manage-cost)


# Understanding cost
Source: https://docs.pinecone.io/guides/manage-cost/understanding-cost

Understand how costs are incurred in Pinecone, including read units (RUs), write units (WUs), storage, egress, and embedding.

For the latest pricing details, see [Pricing](https://www.pinecone.io/pricing/).

Pinecone serverless is usage-based, so you pay only for the data you store and the operations you run. Idle indexes cost nothing. Most early and small workloads fit within the free [Starter plan](https://www.pinecone.io/pricing/), and you can lower costs further as you scale.

## Ways to reduce cost

* **Start free.** The Starter plan has no monthly minimum, so you can build and test before committing to any spend.
* **Prepaid credits and annual commitments.** Committing usage upfront earns discounted rates. See [Prepaid credits](#prepaid-credits).
* **Bulk import credit.** Standard and Enterprise organizations receive a one-time 1 TB import credit for loading data from object storage. See [Imports](#imports).
* **Optimize your workload.** Use namespaces and right-size your reads to cut ongoing query cost. See [Save on costs](/guides/optimize/save-on-costs).
* **Talk to us.** Standard and Enterprise customers can [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) to optimize costs and discuss volume discounts.

## Minimum usage

The Builder, Standard, and Enterprise [pricing plans](https://www.pinecone.io/pricing/) include a monthly minimum usage commitment:

| Plan       | Minimum usage     |
| ---------- | ----------------- |
| Starter    | \$0/month         |
| Builder    | \$20/month (flat) |
| Standard   | \$50/month        |
| Enterprise | \$500/month       |

On the Builder plan, the monthly minimum is a flat fee that covers included usage; additional usage beyond [Builder limits](/reference/api/database-limits) is blocked rather than billed. On the Standard and Enterprise plans, customers are charged for what they use each month beyond the monthly minimum.

The minimum is a commitment you grow into rather than an extra charge. Once your usage exceeds the minimum, you pay only for what you use.

**Examples**

<AccordionGroup>
  <Accordion title="Usage below monthly minimum">
    * You are on the Standard plan.
    * Your usage for the month of August amounts to \$20.
    * Your usage is below the \$50 monthly minimum, so your total for the month is \$50.

    In this case, the August invoice would include line items for each service you used (totaling \$20), plus a single line item covering the rest of the minimum usage commitment (\$30).
  </Accordion>

  <Accordion title="Usage exceeds monthly minimum">
    * You are on the Standard plan.
    * Your usage for the month of August amounts to \$100.
    * Your usage exceeds the \$50 monthly minimum, so your total for the month is \$100.

    In this case, the August invoice would only show line items for each service you used (totaling \$100). Since your usage exceeds the minimum usage commitment, you are only charged for your actual usage and no additional minimum usage line item appears on your invoice.
  </Accordion>
</AccordionGroup>

## Prepaid credits

Pinecone offers an incentive for customers who purchase prepaid credits with an upfront payment. Customers may purchase between \$8,000 and \$25,000 in prepaid credits.

Customers who purchase prepaid credits can unlock additional usage capacity at no extra cost. The available benefits vary based on the selected plan and prepaid amount.

Prepaid credits apply to Pinecone services at List Price. Any usage that exceeds the available prepaid credits will be billed at full List Price.

Customers on Standard and Enterprise pay-as-you-go plans can purchase prepaid credits directly by navigating in the Pinecone console to [Settings > Billing > Plans](https://app.pinecone.io/organizations/-/settings/billing/plans).

<Note>
  Purchasing prepaid credits is not available through cloud marketplace billing. To purchase prepaid credits through a cloud marketplace, contact [ar@pinecone.io](mailto:ar@pinecone.io).
</Note>

## Serverless indexes

With serverless indexes, you pay for the amount of data stored and operations performed, based on four usage metrics: [read units](#read-units), [write units](#write-units), [storage](#storage), and [egress](#egress).

For the latest serverless pricing rates, see [Pricing](https://www.pinecone.io/pricing/).

### Read units

A **read unit (RU)** is the unit Pinecone uses to measure and price the cost of a read request. Read units (RUs) measure the compute, I/O, and network resources consumed by the following read requests:

* [Query](#query)
* [Fetch](#fetch)
* [List](#list)

<Tip>
  Read requests return the number of RUs used. You can use this information to [monitor read costs](/guides/manage-cost/monitor-usage-and-costs#read-units).
</Tip>

<Note>
  Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide.
</Note>

#### Query

The cost of a query scales linearly with the size of the targeted namespace. Specifically, a query uses 1 RU for every 1 GB of namespace size, with a minimum of 0.25 RUs per query.

| Namespace size | Read units per query |
| :------------- | :------------------- |
| \< 0.25 GB     | 0.25 RUs (minimum)   |
| 1 GB           | 1 RU                 |
| 10 GB          | 10 RUs               |
| 50 GB          | 50 RUs               |
| 100 GB         | 100 RUs              |

To learn how to calculate your namespace size, see [Storage](#storage).

<Note>
  Parameters that affect the size of the query response, such as `top_k`, `include_metadata`, and `include_values`, are not relevant for query cost; only the size of the namespace determines the number of RUs used.
</Note>

#### Fetch

A fetch request uses 1 RU for every 10 records fetched, for example:

| Fetched records | RUs |
| --------------- | --- |
| 10              | 1   |
| 50              | 5   |
| 107             | 11  |

Specifying a non-existent ID or adding the same ID more than once does not increase the number of RUs used. However, a fetch request will always use at least 1 RU.

<Note>
  [Fetching records by metadata](/guides/manage-data/fetch-data#fetch-records-by-metadata) uses the same cost model as fetching by ID: 1 RU for every 10 records fetched.
</Note>

#### List

List has a fixed cost of 1 RU per call, with up to 100 records per call.

### Write units

A **write unit (WU)** is the unit Pinecone uses to measure and price the cost of a write request. Write units (WUs) measure the storage and compute resources used by the following write requests:

* [Upsert](#upsert)
* [Update](#update)
* [Delete](#delete)

#### Upsert

An upsert request uses 1 WU for each 1 KB of the request, with a minimum of 5 WUs per request. When an upsert modifies an existing record, the request uses 1 WU for each 1 KB of the existing record as well.

For example, the following table shows the WUs used by upsert requests at different batch sizes and record sizes, assuming all records are new:

| Records per batch | Dimension | Avg. metadata size | Avg. record size | WUs  |
| :---------------- | :-------- | :----------------- | :--------------- | :--- |
| 1                 | 768       | 100 bytes          | 3.2 KB           | 5    |
| 2                 | 768       | 100 bytes          | 3.2 KB           | 7    |
| 10                | 1024      | 15,000 bytes       | 19.10 KB         | 191  |
| 100               | 768       | 500 bytes          | 3.57 KB          | 357  |
| 1000              | 1536      | 1000 bytes         | 7.14 KB          | 7140 |

#### Update

An update request uses 1 WU for each 1 KB of the new and existing record, with a minimum of 5 WUs per request.

For example, the following table shows the WUs used by an update at different record sizes:

| New record size | Previous record size | WUs |
| :-------------- | :------------------- | :-- |
| 6.24 KB         | 6.50 KB              | 13  |
| 19.10 KB        | 15 KB                | 25  |
| 3.57 KB         | 5 KB                 | 9   |
| 7.14 KB         | 10 KB                | 18  |
| 3.17 KB         | 3.17 KB              | 7   |

<Note>
  [Updating records by metadata](/guides/manage-data/update-data#update-by-metadata) uses the same cost model as updating by ID: 1 WU for each 1 KB of the new and existing record.
</Note>

#### Delete

A delete request uses 1 WU for each 1 KB of records deleted, with a minimum of 5 WUs per request.

For example, the following table shows the WUs used by delete requests at different batch sizes and record sizes:

| Records per batch | Dimension | Avg. metadata size | Avg. record size | WUs  |
| :---------------- | :-------- | :----------------- | :--------------- | :--- |
| 1                 | 768       | 100 bytes          | 3.2 KB           | 5    |
| 2                 | 768       | 100 bytes          | 3.2 KB           | 7    |
| 10                | 1024      | 15,000 bytes       | 19.10 KB         | 191  |
| 100               | 768       | 500 bytes          | 3.57 KB          | 357  |
| 1000              | 1536      | 1000 bytes         | 7.14 KB          | 7140 |

Specifying a non-existent ID or adding the same ID more than once does not increase WU use.

[Deleting a namespace](/guides/manage-data/manage-namespaces#delete-a-namespace) or [deleting all records in a namespace using `deleteAll`](/guides/manage-data/delete-data#delete-all-records-in-a-namespace) uses 5 WUs.

<Note>
  [Deleting records by metadata](/guides/manage-data/delete-data#delete-records-by-metadata) uses the same cost model as deleting by ID: 1 WU for each 1 KB of records deleted.
</Note>

### Storage

Storage costs are based on the size of an index on a per-gigabyte (GB) monthly rate. The size of an index is defined as the total size of its records across all namespaces. For the latest storage pricing rates, see [Pricing](https://www.pinecone.io/pricing/).

A record can include a dense vector, a sparse vector, or both. Use the formula that matches your data to calculate total size:

<div>
  <Tabs>
    <Tab title="Index of dense vectors">
      An [index of dense vectors](/guides/index-data/indexing-overview#indexes-with-dense-vectors) contains records with one dense vector each.

      <Note>
        Records can also contain sparse vectors (when the index metric is set to `dotproduct`), which can be useful for [hybrid search](/guides/search/hybrid-search#use-a-single-index-for-dense-and-sparse-vectors). To learn how to calculate size in that case, see [Index with both dense and sparse vectors](#index-with-both-dense-and-sparse-vectors).
      </Note>

      **Calculate size (assuming no sparse vectors)**

      ```
      Index size = Number of records × (
                     ID size + 
                     Metadata size +
                     Dense vector dimensions × 4 bytes
                   )
      ```

      Where:

      * `ID size` and `Metadata size` are measured in bytes, averaged across all records.
      * Each `Dense vector dimension` uses 4 bytes.

      **Example calculations**

      These examples assume 8-byte IDs:

      | Records    | Dense vector dimensions | Avg metadata size | Index size |
      | :--------- | :---------------------- | :---------------- | :--------- |
      | 500,000    | 768                     | 500 bytes         | 1.79 GB    |
      | 1,000,000  | 1536                    | 1,000 bytes       | 7.15 GB    |
      | 5,000,000  | 1024                    | 15,000 bytes      | 95.5 GB    |
      | 10,000,000 | 1536                    | 1,000 bytes       | 71.5 GB    |

      <Note>
        Example: 500,000 records × (8-byte ID + (768 dense vector dimensions × 4 bytes) + 500 bytes of metadata) = 1.79 GB
      </Note>
    </Tab>

    <Tab title="Index of sparse vectors">
      An [index of sparse vectors](/guides/index-data/indexing-overview#indexes-with-sparse-vectors) contains records with one sparse vector each.

      **Calculate size**

      ```
      Index size = Number of records × (
                     ID size + 
                     Metadata size +
                     Number of non-zero sparse values × 8 bytes
                   )
      ```

      Where:

      * `ID size` and `Metadata size` are measured in bytes, averaged across all records.
      * `Number of non-zero sparse values`: Average number across all records. To find the count for a single record, check the length of the sparse vector's `indices` or `values` array. Each non-zero value uses 8 bytes.

      **Example calculations**

      These examples assume 8-byte IDs:

      | Records    | Avg number of non-zero sparse values | Avg metadata size | Index size |
      | :--------- | :----------------------------------- | :---------------- | :--------- |
      | 500,000    | 10                                   | 500 bytes         | 0.29 GB    |
      | 1,000,000  | 50                                   | 1,000 bytes       | 1.41 GB    |
      | 5,000,000  | 100                                  | 15,000 bytes      | 79.0 GB    |
      | 10,000,000 | 50                                   | 1,000 bytes       | 14.1 GB    |

      <Note>
        Example: 500,000 records × (8-byte ID + (10 non-zero sparse values × 8 bytes) + 500 bytes of metadata) = 0.29 GB
      </Note>
    </Tab>

    <Tab title="Index with both dense and sparse vectors">
      An [index with both dense and sparse vectors](/guides/search/hybrid-search#use-a-single-index-for-dense-and-sparse-vectors) contains records that each have one dense vector and an optional sparse vector.

      **Calculate size**

      ```
      Index size = Number of records × (
                     ID size + 
                     Metadata size +
                     Dense vector dimensions × 4 bytes + 
                     Number of non-zero sparse values × 8 bytes
                   )
      ```

      Where:

      * `ID size` and `Metadata size` are measured in bytes, averaged across all records.
      * Each `Dense vector dimension` uses 4 bytes.
      * `Number of non-zero sparse values`: Average number across all records, including those without sparse vectors. To find the count for a single record, check the length of the sparse vector's `indices` or `values` array. Each non-zero value uses 8 bytes.

      **Example calculations**

      These examples assume 8-byte IDs:

      | Records    | Dense vector dimensions | Avg number of non-zero sparse values | Avg metadata size | Index size |
      | :--------- | :---------------------- | :----------------------------------- | :---------------- | :--------- |
      | 500,000    | 768                     | 10                                   | 500 bytes         | 1.83 GB    |
      | 1,000,000  | 1536                    | 50                                   | 1,000 bytes       | 7.54 GB    |
      | 5,000,000  | 1024                    | 100                                  | 15,000 bytes      | 99.5 GB    |
      | 10,000,000 | 1536                    | 50                                   | 1,000 bytes       | 75.4 GB    |

      <Note>
        Example: 500,000 records × (8-byte ID + (768 dense vector dimensions × 4 bytes) + (10 non-zero sparse values × 8 bytes) + 500 bytes of metadata) = 1.83 GB
      </Note>
    </Tab>
  </Tabs>
</div>

### Egress

**Egress** measures the data Pinecone returns to you on serverless reads. Egress is measured in GB of total response bytes returned by an in-scope read request, proportional to the record data returned (IDs, scores, values, and metadata).

Egress is metered on read requests that return per-record data:

* [Query](/guides/search/search-overview)
* [Fetch](/guides/manage-data/fetch-data) (by ID and by metadata)
* [List](/guides/manage-data/list-record-ids)
* [Text search](/reference/api/latest/data-plane/search_records) on integrated indexes
* [Full-text search](/guides/search/full-text-search)

Write requests (upsert, update, delete, import), index statistics (such as `describe_index_stats`), and index management requests are not metered for egress.

<Note>
  Egress accrues on all bytes returned by in-scope reads, including IDs, scores, and metadata. Setting `include_values=false` on a [fetch](/guides/manage-data/fetch-data#fetch-records) or query lowers egress but does not exempt the request, because IDs and metadata are still returned.
</Note>

<Tip>
  In-scope read requests return the egress consumed in the response `usage` object. You can use this information to [monitor egress](/guides/manage-cost/monitor-usage-and-costs#egress).
</Tip>

#### Egress allowance

Each plan includes a monthly egress allowance, which resets at the start of each billing period:

| Plan       | Monthly egress allowance |
| :--------- | :----------------------- |
| Free       | 1 GB                     |
| Builder    | 10 GB                    |
| Standard   | 100 GB                   |
| Enterprise | 100 GB                   |

What happens past the allowance depends on your plan:

* **Usage-based plans (Standard, Enterprise):** egress beyond the allowance is billed at the per-GB overage rate and reads keep serving. For the latest egress rate, see [Pricing](https://www.pinecone.io/pricing/).
* **Flat-fee plans (Free, Builder):** in-scope reads are blocked with a `RESOURCE_EXHAUSTED` (429) error and an upgrade prompt once the allowance is reached. Index statistics, index management, and write requests remain available, and the allowance resets at the start of the next billing period.

## Imports

[Importing from object storage](/guides/index-data/import-data) is the most efficient and cost-effective method to load large numbers of records into an index. The cost of an import is based on the size of the records read, whether the records were imported successfully or not.

If the import operation fails (e.g., after encountering a vector of the wrong dimension in an import with `on_error="abort"`), you will still be charged for the records read. However, if the import fails because of an internal system error, you will not incur charges. In this case, the import will return the error message `"We were unable to process your request. If the problem persists, please contact us at https://support.pinecone.io"`.

<Note>
  Standard and Enterprise organizations receive a **one-time 1 TB bulk import credit**, valid through August 30, 2026. Usage beyond the free allotment is billed at the standard import rate. Builder and Starter plans are not eligible.
</Note>

For the latest import pricing rates, see [Pricing](https://www.pinecone.io/pricing/).

## Backups and restores

A [backup](/guides/manage-data/backups-overview) is a static copy of a serverless index. Both the cost of storing a backup and [restoring an index](/guides/manage-data/restore-an-index) from a backup is based on the size of the index. For the latest backup and restore pricing rates, see [Pricing](https://www.pinecone.io/pricing/).

## Embedding

Pinecone hosts several [embedding models](/guides/index-data/create-an-index#embedding-models) so it's easy to manage your vector storage and search process on a single platform. You can use a hosted model to embed your data as an integrated part of upserting and querying, or you can use a hosted model to embed your data as a standalone operation.

Embedding costs are determined by how many [tokens](https://www.pinecone.io/learn/tokenization/) are in a request. In general, the more words contained in your passage or query, the more tokens you generate.

For example, if you generate embeddings for the query, "What is the maximum diameter of a red pine?", Pinecone Inference generates 10 tokens, then converts them into an embedding. If the price per token for your billing plan is \$.08 per million tokens, then this API call costs \$.00001.

To learn more about tokenization, see [Choosing an embedding model](https://www.pinecone.io/learn/series/rag/embedding-models-rundown/). For the latest embed pricing rates, see [Pricing](https://www.pinecone.io/pricing/).

<Tip>
  Embedding requests returns the total tokens generated. You can use this information to [monitor and manage embedding costs](/guides/manage-cost/monitor-usage-and-costs#embedding-tokens).
</Tip>

## Reranking

Pinecone hosts several [reranking models](/guides/search/rerank-results#reranking-models) so it's easy to manage two-stage vector retrieval on a single platform. You can use a hosted model to rerank results as an integrated part of a query, or you can use a hosted model to rerank results as a standalone operation.

Reranking costs are determined by the number of requests to the reranking model. For the latest rerank pricing rates, see [Pricing](https://www.pinecone.io/pricing/).

## Assistant

For details on how costs are incurred in Pinecone Assistant, see [Assistant pricing](/guides/assistant/pricing-and-limits).

## HIPAA compliance add-on

Full HIPAA compliance is included with the [Enterprise plan](https://www.pinecone.io/pricing/).

For **Standard plan** customers, HIPAA compliance is available as an optional add-on for **\$190 per month**. The add-on is billed monthly and added to your regular invoice. A 6-month minimum period is required.

The HIPAA compliance add-on includes:

* HIPAA-ready infrastructure
* Encrypted data storage
* Audit logging
* Enhanced security controls
* BAA execution and compliance documentation support

<Note>
  If you upgrade to the Enterprise plan, the HIPAA compliance add-on is automatically removed because HIPAA compliance is included with Enterprise.
</Note>

### Enable the HIPAA compliance add-on

To enable the HIPAA compliance add-on, [contact sales](mailto:sales@pinecone.io) or [submit a request](https://www.pinecone.io/contact/?contact_form_inquiry_type=Sales). The Pinecone team will review your request and guide you through activation.

## See also

* [Manage cost](/guides/manage-cost/manage-cost)
* [Monitor usage](/guides/manage-cost/monitor-usage-and-costs)
* [Pricing](https://www.pinecone.io/pricing/)


# Back up an index
Source: https://docs.pinecone.io/guides/manage-data/back-up-an-index

Create backups of serverless indexes to protect data, copy indexes, or experiment with configurations using the Pinecone SDK, API, or console.

## Create a backup

You can [create a backup from a serverless index](/reference/api/latest/control-plane/create_backup) as follows.

<Note>
  Backups are supported for indexes without a schema definition and for integrated embedding indexes that use the records API. They are not supported for full-text search indexes with document schemas that include `full_text_search` string fields, `dense_vector` fields, or `sparse_vector` fields. Indexes with document schemas also do not support `semantic_text` fields.
</Note>

<CodeGroup>
  ```python Python theme={null}
  from pinecone import Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")

  backup = pc.create_backup(
      index_name="docs-example", 
      backup_name="example-backup", 
      description="Monthly backup of production index"
  )

  print(backup)
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone';

  const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' })

  const backup = await pc.createBackup({
    indexName: 'docs-example',
    name: 'example-backup',
    description: 'Monthly backup of production index',
  });

  console.log(backup);
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Pinecone;
  import org.openapitools.db_control.client.ApiException;
  import org.openapitools.db_control.client.model.*;

  public class CreateBackup {
      public static void main(String[] args) throws ApiException {
          Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build();

          String indexName = "docs-example";
          String backupName = "example-backup";
          String backupDescription = "Monthly backup of production index";

          BackupModel backup = pc.createBackup(indexName,backupName, backupDescription);

          System.out.println(backup);
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "encoding/json"
      "fmt"
      "log"

      "github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func prettifyStruct(obj interface{}) string {
      bytes, _ := json.MarshalIndent(obj, "", "  ")
      return string(bytes)
  }

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

      indexName := "docs-example"
      backupName := "example-backup"
      backupDesc := "Monthly backup of production index"

      backup, err := pc.CreateBackup(ctx, &pinecone.CreateBackupParams{
          IndexName:   indexName,
          Name:        &backupName,
          Description: &backupDesc,
      })
      if err != nil {
          log.Fatalf("Failed to create backup: %v", err)
      }

      fmt.Printf(prettifyStruct(backup))
  }
  ```

  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  INDEX_NAME="docs-example"

  curl "https://api.pinecone.io/indexes/$INDEX_NAME/backups" \
      -H "Api-Key: $PINECONE_API_KEY" \
      -H 'accept: application/json' \
      -H 'Content-Type: application/json' \
      -H "X-Pinecone-Api-Version: 2025-10" \
      -d '{
        "name": "example-backup", 
        "description": "Monthly backup of production index"
        }'
  ```
</CodeGroup>

The example returns a response like the following:

<CodeGroup>
  ```python Python theme={null}
  {'backup_id': '8c85e612-ed1c-4f97-9f8c-8194e07bcf71',
   'cloud': 'aws',
   'created_at': '2025-05-15T00:52:10.809305882Z',
   'description': 'Monthly backup of production index',
   'dimension': 1024,
   'name': 'example-backup',
   'namespace_count': 3,
   'record_count': 98,
   'region': 'us-east-1',
   'size_bytes': 1069169,
   'source_index_id': 'f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74',
   'source_index_name': 'docs-example',
   'status': 'Ready',
   'tags': {}}
  ```

  ```javascript JavaScript theme={null}
  {
    backupId: '8c85e612-ed1c-4f97-9f8c-8194e07bcf71',
    sourceIndexName: 'docs-example',
    sourceIndexId: 'f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74',
    name: 'example-backup',
    description: 'Monthly backup of production index',
    status: 'Ready',
    cloud: 'aws',
    region: 'us-east-1',
    dimension: 1024,
    metric: undefined,
    recordCount: 98,
    namespaceCount: 3,
    sizeBytes: 1069169,
    tags: {},
    createdAt: '2025-05-14T16:37:25.625540Z'
  }
  ```

  ```java Java theme={null}
  class BackupModel {
      backupId: 0d75b99f-be61-4a93-905e-77201286c02e
      sourceIndexName: docs-example
      sourceIndexId: f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74
      name: example-backup
      description: Monthly backup of production index
      status: Initializing
      cloud: aws
      region: us-east-1
      dimension: null
      metric: null
      recordCount: null
      namespaceCount: null
      sizeBytes: null
      tags: {}
      createdAt: 2025-05-16T19:42:23.804787550Z
      additionalProperties: null
  }
  ```

  ```go Go theme={null}
  {
    "backup_id": "8c85e612-ed1c-4f97-9f8c-8194e07bcf71",
    "cloud": "aws",
    "created_at": "2025-05-15T00:52:10.809305882Z",
    "description": "Monthly backup of production index",
    "dimension": 1024,
    "name": "example-backup",
    "region": "us-east-1",
    "source_index_id": "f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74",
    "source_index_name": "docs-example",
    "status": "Initializing",
    "tags": {}
  }
  ```

  ```json curl theme={null}
  {
    "backup_id":"8c85e612-ed1c-4f97-9f8c-8194e07bcf71",
    "source_index_id":"f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74",
    "source_index_name":"docs-example",
    "tags":{},
    "name":"example-backup",
    "description":"Monthly backup of production index",
    "status":"Ready",
    "cloud":"aws",
    "region":"us-east-1",
    "dimension":1024,
    "record_count":96,
    "namespace_count":3,
    "size_bytes":1069169,
    "created_at":"2025-05-14T16:37:25.625540Z"
    }
  ```
</CodeGroup>

<Tip>
  You can create a backup using the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/backups).
</Tip>

## Describe a backup

You can [view the details of a backup](/reference/api/latest/control-plane/describe_backup) as follows.

<CodeGroup>
  ```python Python theme={null}
  from pinecone import Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")

  backup = pc.describe_backup(backup_id="8c85e612-ed1c-4f97-9f8c-8194e07bcf71")

  print(backup)
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone';

  const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' })

  const backupDesc = await pc.describeBackup('8c85e612-ed1c-4f97-9f8c-8194e07bcf71');

  console.log(backupDesc);
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Pinecone;
  import org.openapitools.db_control.client.ApiException;
  import org.openapitools.db_control.client.model.*;

  public class CreateBackup {
      public static void main(String[] args) throws ApiException {
          Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build();

          BackupModel backupModel = pc.describeBackup("8c85e612-ed1c-4f97-9f8c-8194e07bcf71");

          System.out.println(backupModel);
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
  	"context"
  	"encoding/json"
  	"fmt"
  	"log"

  	"github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func prettifyStruct(obj interface{}) string {
  	bytes, _ := json.MarshalIndent(obj, "", "  ")
  	return string(bytes)
  }

  func main() {
  	ctx := context.Background()

  	pc, err := pinecone.NewClient(pinecone.NewClientParams{
  		ApiKey: "YOUR_API_KEY",
  	})
  	if err != nil {
  		log.Fatalf("Failed to create Client: %v", err)
  	}

  	backup, err := pc.DescribeBackup(ctx, "8c85e612-ed1c-4f97-9f8c-8194e07bcf71")
  	if err != nil {
  		log.Fatalf("Failed to describe backup: %v", err)
  	}
  	fmt.Printf(prettifyStruct(backup))
  }
  ```

  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  BACKUP_ID="8c85e612-ed1c-4f97-9f8c-8194e07bcf71"

  curl -X GET "https://api.pinecone.io/backups/$BACKUP_ID" \
      -H "Api-Key: $PINECONE_API_KEY" \
      -H "X-Pinecone-Api-Version: 2025-10" \
      -H "accept: application/json"
  ```
</CodeGroup>

The example returns a response like the following:

<CodeGroup>
  ```python Python theme={null}
  {'backup_id': '8c85e612-ed1c-4f97-9f8c-8194e07bcf71',
   'cloud': 'aws',
   'created_at': '2025-05-15T00:52:10.809354Z',
   'description': 'Monthly backup of production index',
   'dimension': 1024,
   'name': 'example-backup',
   'namespace_count': 3,
   'record_count': 98,
   'region': 'us-east-1',
   'size_bytes': 1069169,
   'source_index_id': 'f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74',
   'source_index_name': 'docs-example',
   'status': 'Ready',
   'tags': {}}
  ```

  ```javascript JavaScript theme={null}
  {
    backupId: '8c85e612-ed1c-4f97-9f8c-8194e07bcf71',
    sourceIndexName: 'docs-example',
    sourceIndexId: 'f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74',
    name: 'example-backup',
    description: 'Monthly backup of production index',
    status: 'Ready',
    cloud: 'aws',
    region: 'us-east-1',
    dimension: 1024,
    metric: undefined,
    recordCount: 98,
    namespaceCount: 3,
    sizeBytes: 1069169,
    tags: {},
    createdAt: '2025-05-14T16:37:25.625540Z'
  }
  ```

  ```java Java theme={null}
  class BackupList {
      data: [class BackupModel {
          backupId: 95707edb-e482-49cf-b5a5-312219a51a97
          sourceIndexName: docs-example
          sourceIndexId: f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74
          name: example-backup
          description: Monthly backup of production index
          status: Initializing
          cloud: aws
          region: us-east-1
          dimension: null
          metric: null
          recordCount: null
          namespaceCount: null
          sizeBytes: null
          tags: {}
          createdAt: 2025-05-16T19:46:26.248428Z
          additionalProperties: null
      }]
      pagination: null
      additionalProperties: null
  }
  ```

  ```go Go theme={null}
  {
    "backup_id": "8c85e612-ed1c-4f97-9f8c-8194e07bcf71",
    "cloud": "aws",
    "created_at": "2025-05-15T00:52:10.809354Z",
    "description": "Monthly backup of production index",
    "dimension": 1024,
    "name": "example-backup",
    "namespace_count": 3,
    "record_count": 98,
    "region": "us-east-1",
    "size_bytes": 1069169,
    "source_index_id": "f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74",
    "source_index_name": "docs-example",
    "status": "Ready",
    "tags": {}
  }
  ```

  ```json curl theme={null}
  {
    "backup_id":"8c85e612-ed1c-4f97-9f8c-8194e07bcf71",
    "source_index_id":"f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74",
    "source_index_name":"docs-example",
    "tags":{},
    "name":"example-backup",
    "description":"Monthly backup of production index",
    "status":"Ready",
    "cloud":"aws",
    "region":"us-east-1",
    "dimension":1024,
    "record_count":98,
    "namespace_count":3,
    "size_bytes":1069169,
    "created_at":"2025-03-11T18:29:50.549505Z"
  }
  ```
</CodeGroup>

<Tip>
  You can view backup details using the [Pinecone console](https://app.pinecone.io/organizations/-/projects-/backups).
</Tip>

## List backups for an index

You can [list backups for a specific index](/reference/api/latest/control-plane/list_index_backups) as follows.

Up to 100 backups are returned at a time by default, in sorted order (bitwise “C” collation). If the `limit` parameter is set, up to that number of backups are returned instead. Whenever there are additional backups to return, the response also includes a `pagination_token` that you can use to get the next batch of backups. When the response does not include a `pagination_token`, there are no more backups to return.

<CodeGroup>
  ```python Python theme={null}
  from pinecone import Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")

  index_backups = pc.list_backups(index_name="docs-example")

  print(index_backups)
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone';

  const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' })

  const indexBackups = await pc.listBackups({ indexName: 'docs-example' });

  console.log(indexBackups);
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Pinecone;
  import org.openapitools.db_control.client.ApiException;
  import org.openapitools.db_control.client.model.*;

  public class CreateBackup {
      public static void main(String[] args) throws ApiException {
          Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build();

          String indexName = "docs-example";
          BackupList indexBackupList = pc.listIndexBackups(indexName);

          System.out.println(indexBackupList);
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
  	"context"
  	"encoding/json"
  	"fmt"
  	"log"

  	"github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func prettifyStruct(obj interface{}) string {
  	bytes, _ := json.MarshalIndent(obj, "", "  ")
  	return string(bytes)
  }

  func main() {
  	ctx := context.Background()

  	pc, err := pinecone.NewClient(pinecone.NewClientParams{
  		ApiKey: "YOUR_API_KEY",
  	})
  	if err != nil {
  		log.Fatalf("Failed to create Client: %v", err)
  	}

  	indexName := "docs-example"
  	limit := 2
  	indexBackups, err := pc.ListBackups(ctx, &pinecone.ListBackupsParams{
  		Limit: &limit,
  		IndexName: &indexName,
  	})
  	if err != nil {
  		log.Fatalf("Failed to list backups: %v", err)
  	}
  	fmt.Printf(prettifyStruct(indexBackups))
  }
  ```

  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  INDEX_NAME="docs-example"

  curl -X GET "https://api.pinecone.io/indexes/$INDEX_NAME/backups" \
      -H "Api-Key: $PINECONE_API_KEY" \
      -H "X-Pinecone-Api-Version: 2025-10" \
      -H "accept: application/json"
  ```
</CodeGroup>

The example returns a response like the following:

<CodeGroup>
  ```python Python theme={null}
  [{
      "backup_id": "8c85e612-ed1c-4f97-9f8c-8194e07bcf71",
      "source_index_name": "docs-example",
      "source_index_id": "f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74",
      "status": "Ready",
      "cloud": "aws",
      "region": "us-east-1",
      "tags": {},
      "name": "example-backup",
      "description": "Monthly backup of production index",
      "dimension": 1024,
      "record_count": 98,
      "namespace_count": 3,
      "size_bytes": 1069169,
      "created_at": "2025-05-15T00:52:10.809305882Z"
  }]
  ```

  ```javascript JavaScript theme={null}
  {
    data: [
      {
        backupId: '8c85e612-ed1c-4f97-9f8c-8194e07bcf71',
        sourceIndexName: 'docs-example',
        sourceIndexId: 'f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74',
        name: 'example-backup',
        description: 'Monthly backup of production index',
        status: 'Ready',
        cloud: 'aws',
        region: 'us-east-1',
        dimension: 1024,
        metric: undefined,
        recordCount: 98,
        namespaceCount: 3,
        sizeBytes: 1069169,
        tags: {},
        createdAt: '2025-05-14T16:37:25.625540Z'
      }
    ],
    pagination: undefined
  }
  ```

  ```java Java theme={null}
  class BackupList {
      data: [class BackupModel {
          backupId: 8c85e612-ed1c-4f97-9f8c-8194e07bcf71
          sourceIndexName: docs-example
          sourceIndexId: f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74
          name: example-backup
          description: Monthly backup of production index
          status: Initializing
          cloud: aws
          region: us-east-1
          dimension: null
          metric: null
          recordCount: null
          namespaceCount: null
          sizeBytes: null
          tags: {}
          createdAt: 2025-05-16T19:46:26.248428Z
          additionalProperties: null
      }]
      pagination: null
      additionalProperties: null
  }
  ```

  ```go Go theme={null}
  {
    "data": [
      {
        "backup_id": "bf2cda5d-b233-4a0a-aae9-b592780ad3ff",
        "cloud": "aws",
        "created_at": "2025-05-16T18:01:51.531129Z",
        "description": "Monthly backup of production index",
        "dimension": 0,
        "name": "example-backup",
        "namespace_count": 1,
        "record_count": 96,
        "region": "us-east-1",
        "size_bytes": 86393,
        "source_index_id": "bcb5b3c9-903e-4cb6-8b37-a6072aeb874f",
        "source_index_name": "docs-example",
        "status": "Ready",
        "tags": {}
      },
      {
        "backup_id": "e12269b0-a29b-4af0-9729-c7771dec03e3",
        "cloud": "aws",
        "created_at": "2025-05-14T17:00:45.803146Z",
        "dimension": 0,
        "name": "example-backup2",
        "namespace_count": 1,
        "record_count": 96,
        "region": "us-east-1",
        "size_bytes": 86393,
        "source_index_id": "bcb5b3c9-903e-4cb6-8b37-a6072aeb874f",
        "source_index_name": "docs-example",
        "status": "Ready"
      }
    ],
    "pagination": {
      "next": "eyJsaW1pdCI6Miwib2Zmc2V0IjoyfQ=="
    }
  }
  ```

  ```json curl theme={null}
  {
    "data":
    [
      {
        "backup_id":"9947520e-d5a1-4418-a78d-9f464c9969da",
        "source_index_id":"8433941a-dae7-43b5-ac2c-d3dab4a56b2b",
        "source_index_name":"docs-example",
        "tags":{},
        "name":"example-backup",
        "description":"Monthly backup of production index",
        "status":"Pending",
        "cloud":"aws",
        "region":"us-east-1",
        "dimension":1024,
        "record_count":98,
        "namespace_count":3,
        "size_bytes":1069169,
        "created_at":"2025-03-11T18:29:50.549505Z"
        }
      ],
    "pagination":null
  }
  ```
</CodeGroup>

<Tip>
  You can view the backups for a specific index from either the [Backups](https://app.pinecone.io/organizations/-/projects/-/backups) tab or the [Indexes](https://app.pinecone.io/organizations/-/projects/-/indexes) tab in the Pinecone console.
</Tip>

## List backups in a project

You can [list backups for all indexes in a project](/reference/api/latest/control-plane/list_project_backups) as follows.

Up to 100 backups are returned at a time by default, in sorted order (bitwise “C” collation). If the `limit` parameter is set, up to that number of backups are returned instead. Whenever there are additional backups to return, the response also includes a `pagination_token` that you can use to get the next batch of backups. When the response does not include a `pagination_token`, there are no more backups to return.

<CodeGroup>
  ```python Python theme={null}
  from pinecone import Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")

  project_backups = pc.list_backups()

  print(project_backups)
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone';

  const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' })

  const projectBackups = await pc.listBackups();

  console.log(projectBackups);
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Pinecone;
  import org.openapitools.db_control.client.ApiException;
  import org.openapitools.db_control.client.model.*;

  public class CreateBackup {
      public static void main(String[] args) throws ApiException {
          Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build();

          String indexName = "docs-example";
          BackupList projectBackupList = pc.listProjectBackups();

          System.out.println(projectBackupList);
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
  	"context"
  	"encoding/json"
  	"fmt"
  	"log"

  	"github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func prettifyStruct(obj interface{}) string {
  	bytes, _ := json.MarshalIndent(obj, "", "  ")
  	return string(bytes)
  }

  func main() {
  	ctx := context.Background()

  	pc, err := pinecone.NewClient(pinecone.NewClientParams{
  		ApiKey: "YOUR_API_KEY",
  	})
  	if err != nil {
  		log.Fatalf("Failed to create Client: %v", err)
  	}

  	limit := 3
  	backups, err := pc.ListBackups(ctx, &pinecone.ListBackupsParams{
  		Limit:     &limit,
  	})
  	if err != nil {
  		log.Fatalf("Failed to list backups: %v", err)
  	}
  	fmt.Printf(prettifyStruct(backups))
  }
  ```

  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"

  curl -X GET "https://api.pinecone.io/backups" \
      -H "Api-Key: $PINECONE_API_KEY" \
      -H "X-Pinecone-Api-Version: 2025-10" \
      -H "accept: application/json"
  ```
</CodeGroup>

The example returns a response like the following:

<CodeGroup>
  ```python Python theme={null}
  [{
      "backup_id": "8c85e612-ed1c-4f97-9f8c-8194e07bcf71",
      "source_index_name": "docs-example",
      "source_index_id": "f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74",
      "status": "Ready",
      "cloud": "aws",
      "region": "us-east-1",
      "tags": {},
      "name": "example-backup",
      "description": "Monthly backup of production index",
      "dimension": 1024,
      "record_count": 98,
      "namespace_count": 3,
      "size_bytes": 1069169,
      "created_at": "2025-05-15T20:26:21.248515Z"
  }, {
      "backup_id": "95707edb-e482-49cf-b5a5-312219a51a97",
      "source_index_name": "docs-example2",
      "source_index_id": "b49f27d1-1bf3-49c6-82b5-4ae46f00f0e6",
      "status": "Ready",
      "cloud": "aws",
      "region": "us-east-1",
      "tags": {},
      "name": "example-backup2",
      "description": "Monthly backup of production index",
      "dimension": 1024,
      "record_count": 97,
      "namespace_count": 2,
      "size_bytes": 1069169,
      "created_at": "2025-05-15T00:52:10.809354Z"
  }, {
      "backup_id": "8c85e612-ed1c-4f97-9f8c-8194e07bcf71",
      "source_index_name": "docs-example3",
      "source_index_id": "f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74",
      "status": "Ready",
      "cloud": "aws",
      "region": "us-east-1",
      "tags": {},
      "name": "example-backup3",
      "description": "Monthly backup of production index",
      "dimension": 1024,
      "record_count": 98,
      "namespace_count": 3,
      "size_bytes": 1069169,
      "created_at": "2025-05-14T16:37:25.625540Z"
  }]
  ```

  ```javascript JavaScript theme={null}
  {
    data: [
      {
        backupId: 'e12269b0-a29b-4af0-9729-c7771dec03e3',
        sourceIndexName: 'docs-example',
        sourceIndexId: 'bcb5b3c9-903e-4cb6-8b37-a6072aeb874f',
        name: 'example-backup',
        description: undefined,
        status: 'Ready',
        cloud: 'aws',
        region: 'us-east-1',
        dimension: 0,
        metric: undefined,
        recordCount: 96,
        namespaceCount: 1,
        sizeBytes: 86393,
        tags: undefined,
        createdAt: '2025-05-14T17:00:45.803146Z'
      },
      {
        backupId: 'd686451d-1ede-4004-9f72-7d22cc799b6e',
        sourceIndexName: 'docs-example2',
        sourceIndexId: 'b49f27d1-1bf3-49c6-82b5-4ae46f00f0e6',
        name: 'example-backup2',
        description: undefined,
        status: 'Ready',
        cloud: 'aws',
        region: 'us-east-1',
        dimension: 1024,
        metric: undefined,
        recordCount: 50,
        namespaceCount: 1,
        sizeBytes: 545171,
        tags: undefined,
        createdAt: '2025-05-14T17:00:34.814371Z'
      },
      {
        backupId: '8c85e612-ed1c-4f97-9f8c-8194e07bcf71',
        sourceIndexName: 'docs-example3',
        sourceIndexId: 'f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74',
        name: 'example-backup3',
        description: 'Monthly backup of production index',
        status: 'Ready',
        cloud: 'aws',
        region: 'us-east-1',
        dimension: 1024,
        metric: undefined,
        recordCount: 98,
        namespaceCount: 3,
        sizeBytes: 1069169,
        tags: {},
        createdAt: '2025-05-14T16:37:25.625540Z'
      }
    ],
    pagination: undefined
  }
  ```

  ```java Java theme={null}
  class BackupList {
      data: [class BackupModel {
          backupId: 13761d20-7a0b-4778-ac27-36dd91c4be43
          sourceIndexName: example-dense-index
          sourceIndexId: f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74
          name: example-backup
          description: Monthly backup of production index
          status: Initializing
          cloud: aws
          region: us-east-1
          dimension: null
          metric: null
          recordCount: null
          namespaceCount: null
          sizeBytes: null
          tags: {}
          createdAt: 2025-05-16T19:46:26.248428Z
          additionalProperties: null
      }, class BackupModel {
          backupId: 0d75b99f-be61-4a93-905e-77201286c02e
          sourceIndexName: example-dense-index
          sourceIndexId: f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74
          name: example-backup2
          description: Monthly backup of production index
          status: Initializing
          cloud: aws
          region: us-east-1
          dimension: null
          metric: null
          recordCount: null
          namespaceCount: null
          sizeBytes: null
          tags: {}
          createdAt: 2025-05-16T19:42:23.804820Z
          additionalProperties: null
      }, class BackupModel {
          backupId: bf2cda5d-b233-4a0a-aae9-b592780ad3ff
          sourceIndexName: example-sparse-index
          sourceIndexId: bcb5b3c9-903e-4cb6-8b37-a6072aeb874f
          name: example-backup3
          description: Monthly backup of production index
          status: Ready
          cloud: aws
          region: us-east-1
          dimension: 0
          metric: null
          recordCount: 96
          namespaceCount: 1
          sizeBytes: 86393
          tags: {}
          createdAt: 2025-05-16T18:01:51.531129Z
          additionalProperties: null
      }]
      pagination: null
      additionalProperties: null
  }
  ```

  ```go Go theme={null}
  {
    "data": [
      {
        "backup_id": "8c85e612-ed1c-4f97-9f8c-8194e07bcf71",
        "cloud": "aws",
        "created_at": "2025-05-15T00:52:10.809305882Z",
        "description": "Monthly backup of production index",
        "dimension": 1024,
        "name": "example-backup",
        "namespace_count": 3,
        "record_count": 98,
        "region": "us-east-1",
        "size_bytes": 1069169,
        "source_index_id": "f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74",
        "source_index_name": "docs-example",
        "status": "Ready",
        "tags": {}
      },
      {
        "backup_id": "bf2cda5d-b233-4a0a-aae9-b592780ad3ff",
        "cloud": "aws",
        "created_at": "2025-05-15T00:52:10.809305882Z",
        "description": "Monthly backup of production index",
        "dimension": 0,
        "name": "example-backup2",
        "namespace_count": 1,
        "record_count": 96,
        "region": "us-east-1",
        "size_bytes": 86393,
        "source_index_id": "bcb5b3c9-903e-4cb6-8b37-a6072aeb874f",
        "source_index_name": "example-sparse-index",
        "status": "Ready",
        "tags": {}
      },
      {
        "backup_id": "f73028f6-1746-410e-ab6d-9dd2519df4de",
        "cloud": "aws",
        "created_at": "2025-05-15T20:26:21.248515Z",
        "description": "Monthly backup of production index",
        "dimension": 1024,
        "name": "example-backup3",
        "namespace_count": 2,
        "record_count": 97,
        "region": "us-east-1",
        "size_bytes": 1069169,
        "source_index_id": "f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74",
        "source_index_name": "example-dense-index",
        "status": "Ready",
        "tags": {}
      }
    ],
    "pagination": {
      "next": "eyJsaW1pdCI6Miwib2Zmc2V0IjoyfQ=="
    }  
  }
  ```

  ```json curl  theme={null}
  {
    "data": [
      {
        "backup_id": "e12269b0-a29b-4af0-9729-c7771dec03e3",
        "source_index_id": "bcb5b3c9-903e-4cb6-8b37-a6072aeb874f",
        "source_index_name": "docs-example",
        "tags": null,
        "name": "example-backup",
        "description": null,
        "status": "Ready",
        "cloud": "aws",
        "region": "us-east-1",
        "dimension": 0,
        "record_count": 96,
        "namespace_count": 1,
        "size_bytes": 86393,
        "created_at": "2025-05-14T17:00:45.803146Z"
      },
      {
        "backup_id": "d686451d-1ede-4004-9f72-7d22cc799b6e",
        "source_index_id": "b49f27d1-1bf3-49c6-82b5-4ae46f00f0e6",
        "source_index_name": "docs-example2",
        "tags": null,
        "name": "example-backup2",
        "description": null,
        "status": "Ready",
        "cloud": "aws",
        "region": "us-east-1",
        "dimension": 1024,
        "record_count": 50,
        "namespace_count": 1,
        "size_bytes": 545171,
        "created_at": "2025-05-14T17:00:34.814371Z"
      },
      {
        "backup_id": "8c85e612-ed1c-4f97-9f8c-8194e07bcf71",
        "source_index_id": "f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74",
        "source_index_name": "docs-example3",
        "tags": {},
        "name": "example-backup3",
        "description": "Monthly backup of production index",
        "status": "Ready",
        "cloud": "aws",
        "region": "us-east-1",
        "dimension": 1024,
        "record_count": 98,
        "namespace_count": 3,
        "size_bytes": 1069169,
        "created_at": "2025-05-14T16:37:25.625540Z"
      }
    ],
    "pagination": null
  }
  ```
</CodeGroup>

<Tip>
  You can view all backups in a project using the [Pinecone console](https://app.pinecone.io/organizations/-/projects-/backups).
</Tip>

## Delete a backup

You can [delete a backup](/reference/api/latest/control-plane/delete_backup) as follows.

<CodeGroup>
  ```python Python theme={null}
  from pinecone import Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")

  pc.delete_backup(backup_id="9947520e-d5a1-4418-a78d-9f464c9969da")
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone';

  const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' })

  await pc.deleteBackup('9947520e-d5a1-4418-a78d-9f464c9969da');
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Pinecone;
  import org.openapitools.db_control.client.ApiException;
  import org.openapitools.db_control.client.model.*;

  public class CreateBackup {
      public static void main(String[] args) throws ApiException {
          Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build();

          pc.deleteBackup("9947520e-d5a1-4418-a78d-9f464c9969da");
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
  	"context"
  	"encoding/json"
  	"fmt"
  	"log"

  	"github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func prettifyStruct(obj interface{}) string {
  	bytes, _ := json.MarshalIndent(obj, "", "  ")
  	return string(bytes)
  }

  func main() {
  	ctx := context.Background()

  	pc, err := pinecone.NewClient(pinecone.NewClientParams{
  		ApiKey: "YOUR_API_KEY",
  	})
  	if err != nil {
  		log.Fatalf("Failed to create Client: %v", err)
  	}

  	err = pc.DeleteBackup(ctx, "8c85e612-ed1c-4f97-9f8c-8194e07bcf71")
  	if err != nil {
  		log.Fatalf("Failed to delete backup: %v", err)
  	} else {
  		fmt.Println("Backup deleted successfully")
  	}
  }
  ```

  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  BACKUP_ID="9947520e-d5a1-4418-a78d-9f464c9969da"

  curl -X DELETE "https://api.pinecone.io/backups/$BACKUP_ID" \
      -H "Api-Key: $PINECONE_API_KEY" \
      -H "X-Pinecone-Api-Version: 2025-10"
  ```
</CodeGroup>

<Tip>
  You can delete a backup using the [Pinecone console](https://app.pinecone.io/organizations/-/projects-/backups).
</Tip>

## Schedule automated backups

Instead of creating backups manually, you can define a recurring schedule that automatically creates backups at a daily, weekly, or monthly frequency. Each schedule includes a retention policy that automatically deletes old backups, keeping storage costs predictable. Each index supports one active schedule at a time.

### Create a backup schedule

<Tabs>
  <Tab title="Pinecone console">
    1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/backups) and go to the **Backups** tab.
    2. Find your index and, in the **Schedule** column, click **add**. Alternatively, select **Schedule backups** from the actions menu of the index.
    3. In the **Add a backup schedule** modal, select a **Frequency** (daily, weekly, or monthly).
    4. Select a **Retention** period. Each backup created by the schedule is automatically deleted after this period.
    5. Click **Add schedule**.

    Pinecone names the schedule and assigns its run time automatically.
  </Tab>

  <Tab title="API">
    <Note>
      The scheduled backups API requires `X-Pinecone-API-Version: unstable`.
    </Note>

    To [create a backup schedule](/reference/api/2026-04/control-plane/create_backup_schedule):

    ```bash curl theme={null}
    curl -sS -X POST "https://api.pinecone.io/indexes/${INDEX_NAME}/backup-schedules" \
      -H "api-key: ${PINECONE_API_KEY}" \
      -H "X-Pinecone-API-Version: unstable" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "my-nightly-backup",
        "schedule": {
          "type": "time-based",
          "frequency": "daily"
        },
        "retention": {
          "expire_after_days": 7
        }
      }'
    ```

    Use `"frequency": "weekly"` or `"monthly"` as needed. The retention policy (`expire_after_days`) is required.
  </Tab>
</Tabs>

### Manage backup schedules

<Tabs>
  <Tab title="Pinecone console">
    1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/backups) and go to the **Backups** tab.
    2. Find your index and, in the **Schedule** column, click the schedule. This opens the **Scheduled backups** page for the index.

    For each schedule, the page shows the frequency, retention period, and next scheduled run time. From here, you can:

    * **Pause or resume a schedule**: Use the toggle on the schedule. An index can have up to three schedules, but only one can be enabled at a time.
    * **Edit a schedule**: Expand the schedule, change the **Frequency** or **Retention**, and click **Update**.
    * **Delete a schedule**: Select **Delete** from the actions menu of the schedule.
  </Tab>

  <Tab title="API">
    <Note>
      The scheduled backups API requires `X-Pinecone-API-Version: unstable`.
    </Note>

    You can [list schedules](/reference/api/2026-04/control-plane/list_backup_schedules), [update a schedule](/reference/api/2026-04/control-plane/update_backup_schedule) (e.g., to pause it or change the frequency), [delete a schedule](/reference/api/2026-04/control-plane/delete_backup_schedule), and [view the backup history](/reference/api/2026-04/control-plane/list_backup_schedule_history) for a schedule.
  </Tab>
</Tabs>

Deleting a schedule does not delete any backups that were previously created by it. For more details, see [Scheduled backups](/guides/manage-data/backups-overview#scheduled-backups).


# Backups overview
Source: https://docs.pinecone.io/guides/manage-data/backups-overview

Learn how serverless index backups work in Pinecone, including scheduled backups, retention policies, and use cases for restoring or copying data.

A backup is a static copy of a serverless [index](/guides/index-data/indexing-overview) that only consumes storage. It is a non-queryable representation of a set of records. You can [create a backup](/guides/manage-data/back-up-an-index) of a serverless index, and you can [create a new serverless index from a backup](/guides/manage-data/restore-an-index). This allows you to restore the index with the same or different configurations.

## Use cases

Creating a backup is useful when performing tasks like the following:

* Protecting an index from manual or system failures.
* Temporarily shutting down an index.
* Copying the data from one index into a different index.
* Making a backup of your index.
* Experimenting with different index configurations.

## Scheduled backups

Instead of creating backups manually, you can define a recurring backup schedule that runs automatically. Each schedule includes:

* **Frequency**: Backups can run daily, weekly, or monthly.
* **Retention**: A required expiration policy that automatically deletes old backups, keeping storage costs predictable.

Each index supports one active schedule at a time. Backups created by a schedule are automatically named `{name}-{ISO8601_timestamp}`.

You can create and manage backup schedules in the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/backups) or with the API. For step-by-step instructions, see [Schedule automated backups](/guides/manage-data/back-up-an-index#schedule-automated-backups).

<Note>
  The scheduled backups API requires `X-Pinecone-API-Version: unstable`.
</Note>

For example, to create a daily backup that expires after 7 days:

```bash theme={null}
curl -sS -X POST "https://api.pinecone.io/indexes/${INDEX_NAME}/backup-schedules" \
  -H "api-key: ${PINECONE_API_KEY}" \
  -H "X-Pinecone-API-Version: unstable" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-nightly-backup",
    "schedule": {
      "type": "time-based",
      "frequency": "daily"
    },
    "retention": {
      "expire_after_days": 7
    }
  }'
```

Deleting a schedule does not delete any backups that were previously created by it. If you delete an index, all associated schedules are automatically deleted.

For more details, see the API reference:

* [Create backup schedule](/reference/api/2026-04/control-plane/create_backup_schedule)
* [List backup schedules](/reference/api/2026-04/control-plane/list_backup_schedules)
* [Describe backup schedule](/reference/api/2026-04/control-plane/describe_backup_schedule)
* [Update backup schedule](/reference/api/2026-04/control-plane/update_backup_schedule)
* [Delete backup schedule](/reference/api/2026-04/control-plane/delete_backup_schedule)
* [List schedule history](/reference/api/2026-04/control-plane/list_backup_schedule_history)

## Performance

Backup and restore times depend upon the size of the index and number of namespaces:

* For less than 1M vectors in a namespace, backups and restores take approximately 10 minutes.
* For 100,000,000 vectors, backups and restores can take up to 5 hours.

## Quotas

| Metric              | Starter plan | Builder plan | Standard plan | Enterprise plan |
| :------------------ | :----------- | :----------- | :------------ | :-------------- |
| Backups per project | N/A          | N/A          | 500           | 1000            |

<Note>
  Backups are not available on the Starter or Builder plans. To create backups, [upgrade to the Standard or Enterprise plan](/guides/organizations/manage-billing/upgrade-billing-plan).
</Note>

## Limitations

Backup limitations are as follows:

* Backups are stored in the same project, cloud provider, and region as the source index.
* You can only restore an index to the same project and cloud provider as the source index. Restoring to a different region on the same cloud provider is supported using the `unstable` API version. For details, see [Restore to a different region](/guides/manage-data/restore-an-index#restore-to-a-different-region).
* Backups only include vectors that were in the index at least 15 minutes prior to the backup time. This means that if a vector was inserted into an index and a backup was immediately taken after, the recently inserted vector may not be backed up. More specifically, if a backup is created only a few minutes after the source index was created, the backup may have 0 vectors.
* You can only perform operations on backups in the current Pinecone project.
* Backups are supported for indexes without a schema definition and for integrated embedding indexes that use the records API. They are not supported for full-text search indexes with document schemas that include `full_text_search` string fields, `dense_vector` fields, or `sparse_vector` fields. Indexes with document schemas also do not support `semantic_text` fields.

## Backup and restore cost

* To understand how cost is calculated for backups and restores, see [Understanding cost](/guides/manage-cost/understanding-cost#backups-and-restores).
* For up-to-date pricing information, see [Pricing](https://www.pinecone.io/pricing/).


# Delete records
Source: https://docs.pinecone.io/guides/manage-data/delete-data

Delete records from a Pinecone index namespace by ID or metadata filter, including delete-by-ID, delete-all, and delete-by-metadata operations.

This page shows you how to [delete](/reference/api/latest/data-plane/delete) records from an index [namespace](/guides/index-data/indexing-overview#namespaces).

<Tip>
  Deletes consume [write units (WUs)](/guides/manage-cost/understanding-cost#write-units). See [Understanding cost](/guides/manage-cost/understanding-cost#delete) for how delete cost is calculated.
</Tip>

## Delete records by ID

Since Pinecone records can always be efficiently accessed using their ID, deleting by ID is the most efficient way to remove specific records from a namespace.

<Note>
  To remove records from the default namespace, specify `"__default__"` as the namespace in your request.
</Note>

<CodeGroup>
  ```Python Python theme={null}
  # pip install "pinecone[grpc]"
  from pinecone.grpc import PineconeGRPC as Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")

  # To get the unique host for an index, 
  # see https://docs.pinecone.io/guides/manage-data/target-an-index
  index = pc.Index(host="INDEX_HOST")

  index.delete(ids=["id-1", "id-2"], namespace='example-namespace')
  ```

  ```JavaScript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone'

  const pc = new Pinecone({ apiKey: "YOUR_API_KEY" })

  // To get the unique host for an index, 
  // see https://docs.pinecone.io/guides/manage-data/target-an-index
  const index = pc.index("INDEX_NAME", "INDEX_HOST")

  const ns = index.namespace('example-namespace')
  // Delete one record by ID.
  await ns.deleteOne('id-1');
  // Delete more than one record by ID.
  await ns.deleteMany(['id-2', 'id-3']);
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Index;
  import io.pinecone.configs.PineconeConfig;
  import io.pinecone.configs.PineconeConnection;

  import java.util.Arrays;
  import java.util.List;

  public class DeleteExample {
      public static void main(String[] args) {
          PineconeConfig config = new PineconeConfig("YOUR_API_KEY");
          // To get the unique host for an index, 
          // see https://docs.pinecone.io/guides/manage-data/target-an-index
          config.setHost("INDEX_HOST");
          PineconeConnection connection = new PineconeConnection(config);
          Index index = new Index(connection, "INDEX_NAME");
          List<String> ids = Arrays.asList("id-1", "id-2");
          index.deleteByIds(ids, "example-namespace");
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "log"

      "github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

      // To get the unique host for an index, 
      // see https://docs.pinecone.io/guides/manage-data/target-an-index
      idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST", Namespace: "example-namespace"})
      if err != nil {
          log.Fatalf("Failed to create IndexConnection for Host: %v", err)
    	}

      id1 := "id-1"
      id2 := "id-2"

      err = idxConnection.DeleteVectorsById(ctx, []string{id1, id2})
      if err != nil {
          log.Fatalf("Failed to delete vector with ID %v: %v", id, err)
      }
  }
  ```

  ```bash curl theme={null}
  # To get the unique host for an index,
  # see https://docs.pinecone.io/guides/manage-data/target-an-index
  PINECONE_API_KEY="YOUR_API_KEY"
  INDEX_HOST="INDEX_HOST"

  curl "https://$INDEX_HOST/vectors/delete" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H 'Content-Type: application/json' \
    -H "X-Pinecone-Api-Version: 2025-10" \
    -d '{
      "ids": [
        "id-1", 
        "id-2"
      ],
      "namespace": "example-namespace"
    }
  '
  ```
</CodeGroup>

## Delete records by metadata

To delete records from a namespace based on their metadata values, pass a [metadata filter expression](/guides/index-data/indexing-overview#metadata-filter-expressions) to the `delete` operation. This deletes all records in the namespace that match the filter expression.

For example, the following code deletes all records with a `genre` field set to `documentary` from namespace `example-namespace`:

<CodeGroup>
  ```Python Python theme={null}
  # pip install "pinecone[grpc]"
  from pinecone.grpc import PineconeGRPC as Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")

  # To get the unique host for an index, 
  # see https://docs.pinecone.io/guides/manage-data/target-an-index
  index = pc.Index(host="INDEX_HOST")

  index.delete(
      filter={
          "genre": {"$eq": "documentary"}
      },
      namespace="example-namespace" 
  )
  ```

  ```JavaScript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone'

  const pc = new Pinecone({ apiKey: "YOUR_API_KEY" })

  // To get the unique host for an index, 
  // see https://docs.pinecone.io/guides/manage-data/target-an-index
  const index = pc.index("INDEX_NAME", "INDEX_HOST")

  const ns = index.namespace('example-namespace')

  await ns.deleteMany({
    genre: { $eq: "documentary" },
  });
  ```

  ```java Java theme={null}
  import com.google.protobuf.Struct;
  import com.google.protobuf.Value;
  import io.pinecone.clients.Index;
  import io.pinecone.configs.PineconeConfig;
  import io.pinecone.configs.PineconeConnection;

  import java.util.Arrays;
  import java.util.List;

  public class DeleteExample {
      public static void main(String[] args) {
          PineconeConfig config = new PineconeConfig("YOUR_API_KEY");
          // To get the unique host for an index, 
          // see https://docs.pinecone.io/guides/manage-data/target-an-index
          config.setHost("INDEX_HOST");
          PineconeConnection connection = new PineconeConnection(config);
          Index index = new Index(connection, "INDEX_NAME");
          Struct filter = Struct.newBuilder()
                  .putFields("genre", Value.newBuilder()
                          .setStructValue(Struct.newBuilder()
                                  .putFields("$eq", Value.newBuilder()
                                          .setStringValue("documentary")
                                          .build()))
                          .build())
                  .build();
          index.deleteByFilter(filter, "example-namespace");
          
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "log"

      "github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

      // To get the unique host for an index, 
      // see https://docs.pinecone.io/guides/manage-data/target-an-index
      idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST", Namespace: "example-namespace"})
      if err != nil {
          log.Fatalf("Failed to create IndexConnection for Host: %v", err)
    	}

      metadataFilter := map[string]interface{}{
  		"genre": map[string]interface{}{
  			"$eq": "documentary",
  		},
      }

      filter, err := structpb.NewStruct(metadataFilter)
      if err != nil {
          log.Fatalf("Failed to create metadata filter: %v", err)
      }

      err = idxConnection.DeleteVectorsByFilter(ctx, filter)
      if err != nil {
          log.Fatalf("Failed to delete vector(s) with filter %+v: %v", filter, err)
      }
  }
  ```

  ```bash curl theme={null}
  # To get the unique host for an index,
  # see https://docs.pinecone.io/guides/manage-data/target-an-index
  PINECONE_API_KEY="YOUR_API_KEY"
  INDEX_HOST="INDEX_HOST"

  curl -i "https://$INDEX_HOST/vectors/delete" \
    -H 'Api-Key: $PINECONE_API_KEY' \
    -H 'Content-Type: application/json' \
    -H "X-Pinecone-Api-Version: 2025-10" \
    -d '{
      "filter": {"genre": {"$eq": "documentary"}},
      "namespace": "example-namespace"
    }'
  ```
</CodeGroup>

## Delete all records in a namespace

To delete all of the records in a namespace but not the namespace itself, provide a `namespace` parameter and specify the appropriate `deleteAll` parameter for your SDK. To target the default namespace, set `namespace` to `"__default__"`.

<CodeGroup>
  ```Python Python theme={null}
  # pip install "pinecone[grpc]"
  from pinecone.grpc import PineconeGRPC as Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")

  # To get the unique host for an index, 
  # see https://docs.pinecone.io/guides/manage-data/target-an-index
  index = pc.Index(host="INDEX_HOST")

  index.delete(delete_all=True, namespace='example-namespace')
  ```

  ```JavaScript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone'

  const pc = new Pinecone({ apiKey: "YOUR_API_KEY" })

  // To get the unique host for an index, 
  // see https://docs.pinecone.io/guides/manage-data/target-an-index
  const index = pc.index("INDEX_NAME", "INDEX_HOST")

  await index.namespace('example-namespace').deleteAll();
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Index;
  import io.pinecone.configs.PineconeConfig;
  import io.pinecone.configs.PineconeConnection;

  import java.util.Arrays;
  import java.util.List;

  public class DeleteExample {
      public static void main(String[] args) {
          PineconeConfig config = new PineconeConfig("YOUR_API_KEY");
          // To get the unique host for an index, 
          // see https://docs.pinecone.io/guides/manage-data/target-an-index
          config.setHost("INDEX_HOST");
          PineconeConnection connection = new PineconeConnection(config);
          Index index = new Index(connection, "INDEX_NAME");
          index.deleteAll("example-namespace");
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "log"

      "github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

      // To get the unique host for an index, 
      // see https://docs.pinecone.io/guides/manage-data/target-an-index
      idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST", Namespace: "example-namespace"})
      if err != nil {
          log.Fatalf("Failed to create IndexConnection for Host: %v", err)
    	}

      err = idxConnection.DeleteAllVectorsInNamespace(ctx)
      if err != nil {
          log.Fatalf("Failed to delete all vectors in namespace %v: %v", namespace, err)
      }
  }
  ```

  ```bash curl theme={null}
  # To get the unique host for an index,
  # see https://docs.pinecone.io/guides/manage-data/target-an-index
  PINECONE_API_KEY="YOUR_API_KEY"
  INDEX_HOST="INDEX_HOST"

  curl "https://$INDEX_HOST/vectors/delete" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H 'Content-Type: application/json' \
    -H "X-Pinecone-Api-Version: 2025-10" \
    -d '{
      "deleteAll": true,
      "namespace": "example-namespace"
    }
  '
  ```
</CodeGroup>

## Delete an entire namespace

To delete an entire namespace and all of its records, see [Delete a namespace](/guides/manage-data/manage-namespaces#delete-a-namespace).

## Delete an entire index

To remove all records from an index, [delete the index](/guides/manage-data/manage-indexes#delete-an-index) and [recreate it](/guides/index-data/create-an-index).

## Delete limits

**Delete by ID limits:**

| Metric              | Limit                                          |
| :------------------ | :--------------------------------------------- |
| Max IDs per request | 1000 IDs                                       |
| Max request rate    | 5000 records per second per index or namespace |

**Delete by metadata limits:**

| Metric           | Limit                                                                      |
| :--------------- | :------------------------------------------------------------------------- |
| Max request rate | 5 requests per second per namespace<br />500 requests per second per index |

## Data freshness

Pinecone is eventually consistent, so there can be a slight delay before new or changed records are visible to queries. You can view index stats to [check data freshness](/guides/index-data/check-data-freshness).


# Fetch records
Source: https://docs.pinecone.io/guides/manage-data/fetch-data

Retrieve full Pinecone records by ID from a namespace to inspect vector values, metadata, and IDs, or verify upserts using the fetch operation.

<Tip>
  You can fetch data using the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/indexes/-/browser).
</Tip>

<Tip>
  Fetches consume [read units (RUs)](/guides/manage-cost/understanding-cost#read-units). See [Understanding cost](/guides/manage-cost/understanding-cost#fetch) for how fetch cost is calculated.
</Tip>

## Fetch records by ID

To fetch records from a namespace based on their IDs, use the `fetch` operation with the following parameters:

* `namespace`: The [namespace](/guides/index-data/indexing-overview#namespaces) containing the records to fetch. To use the default namespace, set this to `"__default__"`.
* `ids`: The IDs of the records to fetch. Maximum of 1000.

<Note>
  For on-demand indexes, since vector values are retrieved from object storage, fetch operations may have increased latency. If you only need metadata or IDs, consider using the [`query`](/reference/api/latest/data-plane/query) operation with `include_values` set to `false` instead. See [Decrease latency](/guides/optimize/decrease-latency#avoid-including-vector-values-when-not-needed) for more details.
</Note>

<CodeGroup>
  ```Python Python theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")

  # To get the unique host for an index, 
  # see https://docs.pinecone.io/guides/manage-data/target-an-index
  index = pc.Index(host="INDEX_HOST")

  index.fetch(ids=["id-1", "id-2"], namespace="example-namespace")
  ```

  ```JavaScript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone'

  const pc = new Pinecone({ apiKey: "YOUR_API_KEY" })

  // To get the unique host for an index, 
  // see https://docs.pinecone.io/guides/manage-data/target-an-index
  const index = pc.index("INDEX_NAME", "INDEX_HOST")

  const fetchResult = await index.namespace('example-namespace').fetch(['id-1', 'id-2']);
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Index;
  import io.pinecone.configs.PineconeConfig;
  import io.pinecone.configs.PineconeConnection;
  import io.pinecone.proto.FetchResponse;

  import java.util.Arrays;
  import java.util.List;

  public class FetchExample {
      public static void main(String[] args) {
          PineconeConfig config = new PineconeConfig("YOUR_API_KEY");
          // To get the unique host for an index, 
          // see https://docs.pinecone.io/guides/manage-data/target-an-index
          config.setHost("INDEX_HOST");
          PineconeConnection connection = new PineconeConnection(config);
          Index index = new Index(connection, "INDEX_NAME");

          List<String> ids = Arrays.asList("id-1", "id-2");
          FetchResponse fetchResponse = index.fetch(ids, "example-namespace");
          System.out.println(fetchResponse);
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "encoding/json"
      "fmt"
      "log"

      "github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func prettifyStruct(obj interface{}) string {
  	bytes, _ := json.MarshalIndent(obj, "", "  ")
  	return string(bytes)
  }

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

      // To get the unique host for an index, 
      // see https://docs.pinecone.io/guides/manage-data/target-an-index
      idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST", Namespace: "example-namespace"})
      if err != nil {
          log.Fatalf("Failed to create IndexConnection for Host: %v", err)
    	}

      res, err := idxConnection.FetchVectors(ctx, []string{"id-1", "id-2"})
      if err != nil {
          log.Fatalf("Failed to fetch vectors: %v", err)
      } else {
          fmt.Printf(prettifyStruct(res))
      }
  }
  ```

  ```bash curl theme={null}
  # To get the unique host for an index,
  # see https://docs.pinecone.io/guides/manage-data/target-an-index
  PINECONE_API_KEY="YOUR_API_KEY"
  INDEX_HOST="INDEX_HOST"

  curl -X GET "https://$INDEX_HOST/vectors/fetch?ids=id-1&ids=id-2&namespace=example-namespace" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2025-10"
  ```
</CodeGroup>

The response looks like this:

<CodeGroup>
  ```Python Python theme={null}
  {'namespace': 'example-namespace',
   'usage': {'readUnits': 1},
   'vectors': {'id-1': {'id': 'id-1',
                        'values': [0.568879, 0.632687092, 0.856837332, ...]},
               'id-2': {'id': 'id-2',
                        'values': [0.00891787093, 0.581895, 0.315718859, ...]}}}
  ```

  ```JavaScript JavaScript theme={null}
  {'namespace': 'example-namespace',
   'usage': {'readUnits': 1},
   'records': {'id-1': {'id': 'id-1',
                        'values': [0.568879, 0.632687092, 0.856837332, ...]},
               'id-2': {'id': 'id-2',
                        'values': [0.00891787093, 0.581895, 0.315718859, ...]}}}
  ```

  ```java Java theme={null}
  namespace: "example-namespace"
  vectors {
    key: "id-1"
    value {
      id: "id-1"
      values: 0.568879
      values: 0.632687092
      values: 0.856837332
      ...
    }
  }
  vectors {
    key: "id-2"
    value {
      id: "id-2"
      values: 0.00891787093
      values: 0.581895
      values: 0.315718859
      ...
    }
  }
  usage {
    read_units: 1
  }
  ```

  ```go Go theme={null}
  {
    "vectors": {
      "id-1": {
        "id": "id-1",
        "values": [
          -0.0089730695,
          -0.020010853,
          -0.0042787646,
          ...
        ]
      },
      "id-2": {
        "id": "id-2",
        "values": [
          -0.005380766,
          0.00215196,
          -0.014833462,
          ...
        ]
      }
    },
    "usage": {
      "read_units": 1
    }
  }
  ```

  ```json curl theme={null}
  {
    "vectors": {
      "id-1": {
        "id": "id-1",
        "values": [0.568879, 0.632687092, 0.856837332, ...]
      },
      "id-2": {
        "id": "id-2",
        "values": [0.00891787093, 0.581895, 0.315718859, ...]
      }
    },
    "namespace": "example-namespace",
    "usage": {"readUnits": 1},
  }
  ```
</CodeGroup>

## Fetch records by metadata

To fetch records from a namespace based on their metadata values, use the `fetch_by_metadata` operation with the following parameters:

| Parameter         | Required | Description                                                                                                                                                                                                                                                                                                                                         |
| :---------------- | :------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `filter`          | Yes      | A [metadata filter expression](/guides/index-data/indexing-overview#metadata-filter-expressions) describing the records to fetch. Must be present and non-empty.                                                                                                                                                                                    |
| `limit`           | No       | The maximum number of matching records to return in a single response. Defaults to 100; maximum 10,000. To retrieve more than 10,000 matching records, paginate using `paginationToken`.                                                                                                                                                            |
| `namespace`       | No       | The [namespace](/guides/index-data/indexing-overview#namespaces) containing the records to fetch. If omitted or set to an empty string, defaults to the default namespace. To explicitly use the default namespace, set this to `"__default__"`.                                                                                                    |
| `paginationToken` | No       | The `next` token value from the `pagination` object found in a previous response. Include this value to fetch the next page of results, or omit it to start from the beginning. Must be used with the same `namespace` and `filter` parameters that generated it — using an existing token with different parameters will return incorrect results. |

For example, the following code fetches 2 records with a `genre` field set to `Action/Adventure` from the default namespace:

<CodeGroup>
  ```Python Python theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")

  # To get the unique host for an index, 
  # see https://docs.pinecone.io/guides/manage-data/target-an-index
  index = pc.Index(host="INDEX_HOST")

  results = index.fetch_by_metadata(
      filter={"genre": {"$eq": "Action/Adventure"}},
      namespace="__default__",
      limit=2
  )

  print(results)
  ```

  ```JavaScript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone'

  const pc = new Pinecone({ apiKey: "YOUR_API_KEY" })

  // To get the unique host for an index, 
  // see https://docs.pinecone.io/guides/manage-data/target-an-index
  const index = pc.index("INDEX_NAME", "INDEX_HOST")

  const results = await index.fetchByMetadata({
    filter: { genre: { $eq: 'Action/Adventure' } },
    namespace: '__default__',
    limit: 2
  });

  console.log(results);
  ```

  ```java Java theme={null}
  import com.google.protobuf.Struct;
  import com.google.protobuf.Value;
  import io.pinecone.clients.Index;
  import io.pinecone.configs.PineconeConfig;
  import io.pinecone.configs.PineconeConnection;
  import io.pinecone.proto.FetchByMetadataResponse;

  public class FetchByMetadataExample {
      public static void main(String[] args) {
          PineconeConfig config = new PineconeConfig("YOUR_API_KEY");
          // To get the unique host for an index, 
          // see https://docs.pinecone.io/guides/manage-data/target-an-index
          config.setHost("INDEX_HOST");
          PineconeConnection connection = new PineconeConnection(config);
          Index index = new Index(connection, "INDEX_NAME");

          Struct filter = Struct.newBuilder()
              .putFields("genre", Value.newBuilder()
                  .setStructValue(Struct.newBuilder()
                      .putFields("$eq", Value.newBuilder()
                          .setStringValue("Action/Adventure")
                          .build())
                      .build())
                  .build())
              .build();

          FetchByMetadataResponse response = index.fetchByMetadata(
              "__default__", filter, 2, null);

          System.out.println(response);
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "encoding/json"
      "fmt"
      "log"

      "github.com/pinecone-io/go-pinecone/v4/pinecone"
      "google.golang.org/protobuf/types/known/structpb"
  )

  func prettifyStruct(obj interface{}) string {
      bytes, _ := json.MarshalIndent(obj, "", "  ")
      return string(bytes)
  }

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

      // To get the unique host for an index, 
      // see https://docs.pinecone.io/guides/manage-data/target-an-index
      idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST"})
      if err != nil {
          log.Fatalf("Failed to create IndexConnection for Host: %v", err)
      }

      filter, err := structpb.NewStruct(map[string]interface{}{
          "genre": map[string]interface{}{
              "$eq": "Action/Adventure",
          },
      })
      if err != nil {
          log.Fatalf("Failed to create filter: %v", err)
      }

      namespace := "__default__"
      limit := uint32(2)

      res, err := idxConnection.FetchVectorsByMetadata(ctx, &pinecone.FetchVectorsByMetadataRequest{
          Filter:    filter,
          Namespace: &namespace,
          Limit:     &limit,
      })
      if err != nil {
          log.Fatalf("Failed to fetch vectors by metadata: %v", err)
      }
      fmt.Printf(prettifyStruct(res))
  }
  ```

  ```shell curl theme={null}
  # To get the unique host for an index,
  # see https://docs.pinecone.io/guides/manage-data/target-an-index
  PINECONE_API_KEY="YOUR_API_KEY"
  INDEX_HOST="INDEX_HOST"

  curl -X POST "https://$INDEX_HOST/vectors/fetch_by_metadata" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "Content-Type: application/json" \
    -H "X-Pinecone-Api-Version: 2025-10" \
    -d '{
      "namespace": "__default__",
      "filter": {"genre": {"$eq": "Action/Adventure"}},
      "limit": 2
    }'
  ```
</CodeGroup>

The response looks like this:

```json theme={null}
{
  "vectors": {
    "0": {
      "id": "0",
      "values": [
        0.0234527588, 0.0291595459 ...
      ],
      "metadata": {
        "box-office": 2923706026,
        "genre": "Action/Adventure",
        "summary": "On the alien world of Pandora, paraplegic Marine Jake Sully uses an avatar to walk again and becomes torn between his mission and protecting the planet's indigenous Na'vi people. The film stars Sam Worthington, Zoe Saldana, and Sigourney Weaver.",
        "title": "Avatar",
        "year": 2009
      }
    },
    "1": {
      "id": "1",
      "values": [
        0.0397644043, 0.013053894, ...
      ],
      "metadata": {
        "box-office": 2799439100,
        "genre": "Action/Adventure",
        "summary": "In the aftermath of Thanos wiping out half of the universe, the remaining Avengers assemble once more to undo the chaos, leading to a time-traveling adventure. Stars Robert Downey Jr., Chris Evans, and Scarlett Johansson.",
        "title": "Avengers: Endgame",
        "year": 2019
      }
    }
  },
  "namespace": "__default__",
  "usage": {
    "readUnits": 1
  },
  "pagination": {
    "next": "Tm90aGluZyB0byBzZWUgaGVyZQo="
  }
}
```

To fetch the next page of results, pass the pagination token from the previous response. For example:

<CodeGroup>
  ```Python Python theme={null}
  next_results = index.fetch_by_metadata(
      filter={"genre": {"$eq": "Action/Adventure"}},
      namespace="__default__",
      limit=2,
      pagination_token="Tm90aGluZyB0byBzZWUgaGVyZQo="
  )
  ```

  ```JavaScript JavaScript theme={null}
  const nextResults = await index.fetchByMetadata({
    filter: { genre: { $eq: 'Action/Adventure' } },
    namespace: '__default__',
    limit: 2,
    paginationToken: 'Tm90aGluZyB0byBzZWUgaGVyZQo='
  });
  ```

  ```java Java theme={null}
  FetchByMetadataResponse nextPage = index.fetchByMetadata(
      "__default__", filter, 2, "Tm90aGluZyB0byBzZWUgaGVyZQo=");
  ```

  ```go Go theme={null}
  paginationToken := "Tm90aGluZyB0byBzZWUgaGVyZQo="
  nextRes, err := idxConnection.FetchVectorsByMetadata(ctx, &pinecone.FetchVectorsByMetadataRequest{
      Filter:          filter,
      Namespace:       &namespace,
      Limit:           &limit,
      PaginationToken: &paginationToken,
  })
  ```

  ```shell curl theme={null}
  curl -X POST "https://$INDEX_HOST/vectors/fetch_by_metadata" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "Content-Type: application/json" \
    -H "X-Pinecone-Api-Version: 2025-10" \
    -d '{
      "namespace": "__default__",
      "filter": {"genre": {"$eq": "Action/Adventure"}},
      "limit": 2,
      "paginationToken": "Tm90aGluZyB0byBzZWUgaGVyZQo="
    }'
  ```
</CodeGroup>

When there are more results available, the response includes a `pagination` object with a `next` token. When there are no more results, the response does not include a `pagination` object.

## Fetch limits

**Fetch by ID limits:**

| Metric              | Limit                             |
| :------------------ | :-------------------------------- |
| Max IDs per request | 1000 IDs                          |
| Max request size    | N/A                               |
| Max request rate    | 100 requests per second per index |

**Fetch by metadata limits:**

| Metric                   | Limit                               |
| :----------------------- | :---------------------------------- |
| Max records per response | 10,000 records                      |
| Max response size        | 4 MB                                |
| Max request rate         | 5 requests per second per namespace |

To retrieve more than 10,000 matching records, paginate through results using the `paginationToken` parameter. See [Fetch records by metadata](#fetch-records-by-metadata).

## Data freshness

Pinecone is eventually consistent, so there can be a slight delay before new or changed records are visible to queries. You can view index stats to [check data freshness](/guides/index-data/check-data-freshness).


# List record IDs
Source: https://docs.pinecone.io/guides/manage-data/list-record-ids

List the IDs of records in a Pinecone serverless namespace, filter by ID prefix, and paginate results to verify upserts cheaply and quickly.

You can list the IDs of all records in a [namespace](/guides/index-data/indexing-overview#namespaces) or just the records with a common ID prefix.

Using `list` to get record IDs and not the associated data is a cheap and fast way to check [upserts](/guides/index-data/upsert-data).

<Note>
  The `list` endpoint is supported only for serverless indexes.
</Note>

## List the IDs of all records in a namespace

To list the IDs of all records in the namespace of a serverless index, pass only the `namespace` parameter:

<CodeGroup>
  ```python Python theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone

  pc = Pinecone(api_key='YOUR_API_KEY')

  # To get the unique host for an index, 
  # see https://docs.pinecone.io/guides/manage-data/target-an-index
  index = pc.Index(host="INDEX_HOST")

  for ids in index.list(namespace='example-namespace'):
      print(ids)

  # Response:
  # ['doc1#chunk1', 'doc1#chunk2', 'doc1#chunk3']
  ```

  ```js JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone';
  const pc = new Pinecone();

  // To get the unique host for an index, 
  // see https://docs.pinecone.io/guides/manage-data/target-an-index
  const index = pc.index("INDEX_NAME", "INDEX_HOST").namespace("example-namespace");

  const results = await index.listPaginated();
  console.log(results);
  // {
  //   vectors: [
  //     { id: 'doc1#01' }, { id: 'doc1#02' }, { id: 'doc1#03' },
  //     { id: 'doc1#04' }, { id: 'doc1#05' },  { id: 'doc1#06' },
  //     { id: 'doc1#07' }, { id: 'doc1#08' }, { id: 'doc1#09' },
  //     ...
  //   ],
  //   pagination: {
  //     next: 'eyJza2lwX3Bhc3QiOiJwcmVUZXN0LS04MCIsInByZWZpeCI6InByZVRlc3QifQ=='
  //   },
  //   namespace: 'example-namespace',
  //   usage: { readUnits: 1 }
  // }

  // Fetch the next page of results
  await index.listPaginated({ prefix: 'doc1#', paginationToken: results.pagination.next});
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Index;
  import io.pinecone.configs.PineconeConfig;
  import io.pinecone.configs.PineconeConnection;
  import io.pinecone.proto.ListResponse;

  public class ListExample {
      public static void main(String[] args) {
          PineconeConfig config = new PineconeConfig("YOUR_API_KEY");
          // To get the unique host for an index, 
          // see https://docs.pinecone.io/guides/manage-data/target-an-index
          config.setHost("INDEX_HOST");
          PineconeConnection connection = new PineconeConnection(config);
          Index index = new Index(connection, "INDEX_NAME");
          // get the pagination token
          String paginationToken = index.list("example-namespace", 3).getPagination().getNext();
          // get vectors with limit 3 with the paginationToken obtained from the previous step
          ListResponse listResponse = index.list("example-namespace", 3, paginationToken);
      }
  }

  // Response:
  // vectors {
  //   id: "doc1#chunk1"
  // }
  // vectors {
  //   id: "doc1#chunk2"
  // }
  // vectors {
  //   id: "doc2#chunk1"
  // }
  // vectors {
  //   id: "doc3#chunk1"
  // }
  // pagination {
  //   next: "eyJza2lwX3Bhc3QiOiJhbHN0cm9lbWVyaWEtcGVydXZpYW4iLCJwcmVmaXgiOm51bGx9"
  // }
  // namespace: "example-namespace"
  // usage {
  //   read_units: 1
  // }
  ```

  ```go Go theme={null}
  package main

  import (
  	"context"
  	"encoding/json"
  	"fmt"
  	"log"

  	"github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func prettifyStruct(obj interface{}) string {
  	bytes, _ := json.MarshalIndent(obj, "", "  ")
  	return string(bytes)
  }

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

      // To get the unique host for an index, 
      // see https://docs.pinecone.io/guides/manage-data/target-an-index
      idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST", Namespace: "example-namespace"})
      if err != nil {
          log.Fatalf("Failed to create IndexConnection for Host: %v", err)
    	}

      limit := uint32(3)

      res, err := idxConnection.ListVectors(ctx, &pinecone.ListVectorsRequest{
          Limit:  &limit,
      })
      if len(res.VectorIds) == 0 {
          fmt.Println("No vectors found")
  	} else {
  		fmt.Printf(prettifyStruct(res))
  	}
  }

  // Response:
  // {
  //   "vector_ids": [
  //     "doc1#chunk1",
  //     "doc1#chunk2",
  //     "doc1#chunk3"
  //   ],
  //   "usage": {
  //     "read_units": 1
  //   },
  //   "next_pagination_token": "eyJza2lwX3Bhc3QiOiIwMDBkMTc4OC0zMDAxLTQwZmMtYjZjNC0wOWI2N2I5N2JjNDUiLCJwcmVmaXgiOm51bGx9"
  // }
  ```

  ```shell curl theme={null}
  # To get the unique host for an index,
  # see https://docs.pinecone.io/guides/manage-data/target-an-index
  PINECONE_API_KEY="YOUR_API_KEY"
  INDEX_HOST="INDEX_HOST"

  curl -X GET "https://$INDEX_HOST/vectors/list?namespace=example-namespace" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2025-10"

  # Response:
  # {
  #   "vectors": [
  #     { "id": "doc1#chunk1" },
  #     { "id": "doc1#chunk2" },
  #     { "id": "doc1#chunk3" },
  #     { "id": "doc1#chunk4" },
  #    ...
  #   ],
  #   "pagination": {
  #     "next": "c2Vjb25kY2FsbA=="
  #   },
  #   "namespace": "example-namespace",
  #   "usage": {
  #     "readUnits": 1
  #   }
  # }
  ```
</CodeGroup>

## List the IDs of records with a common prefix

ID prefixes enable you to query segments of content. Use the `list` endpoint to list all of the records with the common prefix. For more details, see [Use structured IDs](/guides/index-data/data-modeling#use-structured-ids).

## Paginate through results

The `list` endpoint returns up to 100 IDs per page at a time by default. If the `limit` parameter is passed, `list` returns up to that number of IDs per page instead. For example, if `limit=3`, up to 3 IDs be returned per page. Whenever there are additional IDs to return, the response also includes a `pagination_token` for fetching the next page of IDs.

### Implicit pagination

When using the Python SDK, `list` paginates automatically.

```python Python theme={null}
from pinecone.grpc import PineconeGRPC as Pinecone

pc = Pinecone(api_key='YOUR_API_KEY')

# To get the unique host for an index, 
# see https://docs.pinecone.io/guides/manage-data/target-an-index
index = pc.Index(host="INDEX_HOST")

for ids in index.list(namespace='example-namespace'):
    print(ids)

# Response:
# ['doc1#chunk1', 'doc1#chunk2', 'doc1#chunk3']
# ['doc1#chunk4', 'doc1#chunk5', 'doc1#chunk6']
# ...
```

### Manual pagination

When using the Node.js SDK, Java SDK, Go SDK, or REST API, you must manually fetch each page of results. You can also manually paginate with the Python SDK using `list_paginated()`.

<CodeGroup>
  ```python Python theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone

  pc = Pinecone(api_key='YOUR_API_KEY')

  # To get the unique host for an index, 
  # see https://docs.pinecone.io/guides/manage-data/target-an-index
  index = pc.Index(host="INDEX_HOST")

  namespace = 'example-namespace'

  # For manual control over pagination
  results = index.list_paginated(
      prefix='pref',
      limit=3,
      namespace='example-namespace'
  )
  print(results.namespace)
  print([v.id for v in results.vectors])
  print(results.pagination.next)
  print(results.usage)

  # Results:
  # ['10103-0', '10103-1', '10103-10']
  # eyJza2lwX3Bhc3QiOiIxMDEwMy0=
  # {'read_units': 1}
  ```

  ```js JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone';
  const pc = new Pinecone();

  // To get the unique host for an index, 
  // see https://docs.pinecone.io/guides/manage-data/target-an-index
  const index = pc.index("INDEX_NAME", "INDEX_HOST").namespace("example-namespace");

  const results = await index.listPaginated({ prefix: 'doc1#', limit: 3 });
  console.log(results);

  // Response:
  // {
  //   vectors: [
  //     { id: 'doc1#01' }, { id: 'doc1#02' }, { id: 'doc1#03' }
  //   ],
  //   pagination: {
  //     next: 'eyJza2lwX3Bhc3QiOiJwcmVUZXN0LSCIsInByZWZpeCI6InByZVRlc3QifQ=='
  //   },
  //   namespace: 'example-namespace',
  //   usage: { readUnits: 1 }
  // }
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Index;
  import io.pinecone.configs.PineconeConfig;
  import io.pinecone.configs.PineconeConnection;
  import io.pinecone.proto.ListResponse;

  public class ListExample {
      public static void main(String[] args) {
          PineconeConfig config = new PineconeConfig("YOUR_API_KEY");
          // To get the unique host for an index, 
          // see https://docs.pinecone.io/guides/manage-data/target-an-index
          config.setHost("INDEX_HOST");
          PineconeConnection connection = new PineconeConnection(config);
          Index index = new Index(connection, "INDEX_NAME");
          ListResponse listResponse = index.list("example-namespace", "doc1#" 2); /* Note: You must include an ID prefix to list vector IDs. */
          System.out.println(listResponse.getVectorsList());
          System.out.println(listResponse.getPagination());
      }
  }

  // Response:
  // vectors {
  //   id: "doc1#chunk1"
  // }
  // vectors {
  //   id: "doc1#chunk2"
  // }
  // pagination {
  //   next: "eyJza2lwX3Bhc3QiOiJhbHN0cm9lbWVyaWEtcGVydXZpYW4iLCJwcmVmaXgiOm51bGx9"
  // }
  // namespace: "example-namespace"
  // usage {
  //   read_units: 1
  // }
  ```

  ```go Go theme={null}
  package main

  import (
  	"context"
  	"encoding/json"
  	"fmt"
  	"log"

  	"github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func prettifyStruct(obj interface{}) string {
  	bytes, _ := json.MarshalIndent(obj, "", "  ")
  	return string(bytes)
  }

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

      // To get the unique host for an index, 
      // see https://docs.pinecone.io/guides/manage-data/target-an-index
      idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST", Namespace: "example-namespace"})
      if err != nil {
          log.Fatalf("Failed to create IndexConnection for Host: %v", err)
    	}

      limit := uint32(3)

      res, err := idxConnection.ListVectors(ctx, &pinecone.ListVectorsRequest{
          Limit:  &limit,
      })
      if len(res.VectorIds) == 0 {
          fmt.Println("No vectors found")
      } else {
          fmt.Printf(prettifyStruct(res))
      }
  }

  // Response:
  // {
  //   "vector_ids": [
  //     "doc1#chunk1",
  //     "doc1#chunk2",
  //     "doc1#chunk3"
  //   ],
  //   "usage": {
  //     "read_units": 1
  //   },
  //   "next_pagination_token": "eyJza2lwX3Bhc3QiOiIwMDBkMTc4OC0zMDAxLTQwZmMtYjZjNC0wOWI2N2I5N2JjNDUiLCJwcmVmaXgiOm51bGx9"
  // }
  ```

  ```shell curl theme={null}
  # To get the unique host for an index,
  # see https://docs.pinecone.io/guides/manage-data/target-an-index
  PINECONE_API_KEY="YOUR_API_KEY"
  INDEX_HOST="INDEX_HOST"

  curl -X GET "https://$INDEX_HOST/vectors/list?namespace=example-namespace" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2025-10"

  # Response:
  # {
  #   "vectors": [
  #     { "id": "doc1#chunk1" },
  #     { "id": "doc1#chunk2" },
  #     { "id": "doc1#chunk3" },
  #     { "id": "doc1#chunk4" },
  #    ...
  #   ],
  #   "pagination": {
  #     "next": "c2Vjb25kY2FsbA=="
  #   },
  #   "namespace": "example-namespace",
  #   "usage": {
  #     "readUnits": 1
  #   }
  # }
  ```
</CodeGroup>

Then, to get the next batch of IDs, use the returned `pagination_token`:

<CodeGroup>
  ```python Python theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone

  pc = Pinecone(api_key='YOUR_API_KEY')

  # To get the unique host for an index, 
  # see https://docs.pinecone.io/guides/manage-data/target-an-index
  index = pc.Index(host="INDEX_HOST")

  namespace = 'example-namespace'

  results = index.list_paginated(
      prefix='pref',
      limit=3,
      namespace='example-namespace',
      pagination_token='eyJza2lwX3Bhc3QiOiIxMDEwMy0='
  )
  print(results.namespace)
  print([v.id for v in results.vectors])
  print(results.pagination.next)
  print(results.usage)

  # Response:
  # ['10103-0', '10103-1', '10103-10']
  # xndlsInByZWZpeCI6IjEwMTAzIn0==
  # {'read_units': 1}
  ```

  ```js JavaScript theme={null}
  await index.listPaginated({ prefix: 'doc1#', limit: 3, paginationToken: results.pagination.next});

  // Response:
  // {
  //   vectors: [
  //     { id: 'doc1#10' }, { id: 'doc1#11' }, { id: 'doc1#12' }
  //   ],
  //   pagination: {
  //     next: 'dfajlkjfdsoijeowjoDJFKLJldLIFf34KFNLDSndaklqoLQJORN45afdlkJ=='
  //   },
  //   namespace: 'example-namespace',
  //   usage: { readUnits: 1 }
  // }
  ```

  ```java Java theme={null}
  listResponse = index.list("example-namespace", "doc1#", "eyJza2lwX3Bhc3QiOiJ2MTg4IiwicHJlZml4IjpudWxsfQ==");
  System.out.println(listResponse.getVectorsList());

  // Response:
  // vectors {
  //   id: "doc1#chunk3"
  // }
  // vectors {
  //   id: "doc1#chunk4"
  // }
  // vectors {
  //   id: "doc1#chunk5"
  // }
  // vectors {
  //   id: "doc1#chunk6"
  // }
  // vectors {
  //   id: "doc1#chunk7"
  // }
  // vectors {
  //   id: "doc1#chunk8"
  // }
  // pagination {
  //   next: "eyJza2lwX3Bhc3QiOiJhbHN0cm9lbWVyaWEtcGVydXZpYW4iLCJwcmVmaXgiOm51bGx9"
  // }
  // namespace: "example-namespace"
  // usage {
  //   read_units: 1
  // }
  ```

  ```go Go theme={null}
  package main

  import (
  	"context"
  	"encoding/json"
  	"fmt"
  	"log"

  	"github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func prettifyStruct(obj interface{}) string {
  	bytes, _ := json.MarshalIndent(obj, "", "  ")
  	return string(bytes)
  }

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

      // To get the unique host for an index, 
      // see https://docs.pinecone.io/guides/manage-data/target-an-index
      idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST", Namespace: "example-namespace"})
      if err != nil {
          log.Fatalf("Failed to create IndexConnection for Host: %v", err)
    	}

      limit := uint32(3)
      paginationToken := "dfajlkjfdsoijeowjoDJFKLJldLIFf34KFNLDSndaklqoLQJORN45afdlkJ=="

      res, err := idxConnection.ListVectors(ctx, &pinecone.ListVectorsRequest{
          Limit:  &limit,
          PaginationToken: &paginationToken,
      })
      if len(res.VectorIds) == 0 {
          fmt.Println("No vectors found")
  	} else {
  	    fmt.Printf(prettifyStruct(res))
  	}
  }

  // Response:
  // {
  //   "vector_ids": [
  //     "doc1#chunk4",
  //     "doc1#chunk5",
  //     "doc1#chunk6"
  //   ],
  //   "usage": {
  //     "read_units": 1
  //   },
  //   "next_pagination_token": "eyJza2lwX3Bhc3QiOiIwMDBkMTc4OC0zMDAxLTQwZmMtYjZjNC0wOWI2N2I5N2JjNDUiLCJwcmVmaXgiOm51bGx9"
  // }
  ```

  ```shell curl theme={null}
  # To get the unique host for an index,
  # see https://docs.pinecone.io/guides/manage-data/target-an-index
  PINECONE_API_KEY="YOUR_API_KEY"
  INDEX_HOST="INDEX_HOST"

  curl -X GET "https://$INDEX_HOST/vectors/list?namespace=example-namespace&paginationToken=c2Vjb25kY2FsbA%3D%3D" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2025-10"

  # Response:
  # {
  #   "vectors": [
  #     { "id": "doc2#chunk1" },
  #     { "id": "doc2#chunk1" },
  #     { "id": "doc2#chunk1" },
  #     { "id": "doc2#chunk1" },
  #    ...
  #   ],
  #   "pagination": {
  #     "next": "mn23b4jB3Y9jpsS1"
  #   },
  #   "namespace": "example-namespace",
  #   "usage": {
  #     "readUnits": 1
  #   }
  # }
  ```
</CodeGroup>

When there are no more IDs to return, the response does not includes a `pagination_token`:

<CodeGroup>
  ```python Python theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone

  pc = Pinecone(api_key='YOUR_API_KEY')

  index = pc.Index(host="INDEX_HOST")

  namespace = 'example-namespace'

  results = index.list_paginated(
      prefix='10103',
      limit=3,
      pagination_token='xndlsInByZWZpeCI6IjEwMTAzIn0=='
  )

  print(results.namespace)
  print([v.id for v in results.vectors])
  print(results.pagination.next)
  print(results.usage)

  # Response:
  # ['10103-4', '10103-5', '10103-6']
  # {'read_units': 1}
  ```

  ```js JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone';
  const pc = new Pinecone();

  const index = pc.index("INDEX_NAME", "INDEX_HOST").namespace("example-namespace");

  const results = await index.listPaginated({ prefix: 'doc1#' });
  console.log(results);

  // Response:
  // {
  //   vectors: [
  //     { id: 'doc1#19' }, { id: 'doc1#20' }, { id: 'doc1#21' }
  //   ],
  //   namespace: 'example-namespace',
  //   usage: { readUnits: 1 }
  // }
  ```

  ```go Go theme={null}
  package main

  import (
  	"context"
  	"encoding/json"
  	"fmt"
  	"log"

  	"github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func prettifyStruct(obj interface{}) string {
  	bytes, _ := json.MarshalIndent(obj, "", "  ")
  	return string(bytes)
  }

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

      idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST", Namespace: "example-namespace"})
      if err != nil {
          log.Fatalf("Failed to create IndexConnection for Host: %v", err)
    	}

      limit := uint32(3)
      paginationToken := "eyJza2lwX3Bhc3QiOiIwMDBkMTc4OC0zMDAxLTQwZmMtYjZjNC0wOWI2N2I5N2JjNDUiLCJwcmVmaXgiOm51bGx9"

      res, err := idxConnection.ListVectors(ctx, &pinecone.ListVectorsRequest{
          Limit:  &limit,
          paginationToken: &paginationToken,
      })
      if len(res.VectorIds) == 0 {
          fmt.Println("No vectors found")
    	} else {
  	    fmt.Printf(prettifyStruct(res))
  	}
  }

  // Response:
  // {
  //   "vector_ids": [
  //     "doc1#chunk7",
  //     "doc1#chunk8",
  //     "doc1#chunk9"
  //   ],
  //   "usage": {
  //     "read_units": 1
  //   }
  // }
  ```

  ```shell curl theme={null}
  # To get the unique host for an index,
  # see https://docs.pinecone.io/guides/manage-data/target-an-index
  PINECONE_API_KEY="YOUR_API_KEY"
  INDEX_HOST="INDEX_HOST"

  curl -X GET "https://$INDEX_HOST/vectors/list?namespace=example-namespace&paginationToken=mn23b4jB3Y9jpsS1" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2025-10"
  # Response:
  # {
  #   "vectors": [
  #     { "id": "doc3#chunk1" },
  #     { "id": "doc5#chunk2" },
  #     { "id": "doc5#chunk3" },
  #     { "id": "doc5#chunk4" },
  #    ...
  #   ],
  #   "namespace": "example-namespace",
  #   "usage": {
  #     "readUnits": 1
  #   }
  # }
  ```
</CodeGroup>


# Manage serverless indexes
Source: https://docs.pinecone.io/guides/manage-data/manage-indexes

List, describe, configure, and delete serverless indexes in Pinecone, including tags, deletion protection, and metadata index configuration.

This page shows you how to manage your existing serverless indexes.

## List indexes

Use the [`list_indexes`](/reference/api/latest/control-plane/list_indexes) operation to get a complete description of all indexes in a project:

<CodeGroup>
  ```Python Python theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")

  index_list = pc.list_indexes()

  print(index_list)
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone'

  const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' })

  const indexList = await pc.listIndexes();

  console.log(indexList);
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Pinecone;
  import org.openapitools.db_control.client.model.*;

  public class ListIndexesExample {
      public static void main(String[] args) {
          Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build();
          IndexList indexList = pc.listIndexes();
          System.out.println(indexList);
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "encoding/json"
      "fmt"
      "log"

      "github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func prettifyStruct(obj interface{}) string {
      bytes, _ := json.MarshalIndent(obj, "", "  ")
      return string(bytes)
  }

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

      idxs, err := pc.ListIndexes(ctx)
      if err != nil {
          log.Fatalf("Failed to list indexes: %v", err)
      } else {
          for _, index := range idxs {
              fmt.Printf("index: %v\n", prettifyStruct(index))
          }
      }
  }
  ```

  ```shell curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"

  curl -i -X GET "https://api.pinecone.io/indexes" \
  -H "Api-Key: $PINECONE_API_KEY" \
  -H "X-Pinecone-Api-Version: 2025-10"
  ```
</CodeGroup>

The response will look like this:

<CodeGroup>
  ```python Python theme={null}
  [{
      "name": "docs-example-sparse",
      "metric": "dotproduct",
      "host": "docs-example-sparse-govk0nt.svc.aped-4627-b74a.pinecone.io",
      "spec": {
          "serverless": {
              "cloud": "aws",
              "region": "us-east-1"
          }
      },
      "status": {
          "ready": true,
          "state": "Ready"
      },
      "vector_type": "sparse",
      "dimension": null,
      "deletion_protection": "disabled",
      "tags": {
          "environment": "development"
      }
  }, {
      "name": "docs-example-dense",
      "metric": "cosine",
      "host": "docs-example-dense-govk0nt.svc.aped-4627-b74a.pinecone.io",
      "spec": {
          "serverless": {
              "cloud": "aws",
              "region": "us-east-1"
          }
      },
      "status": {
          "ready": true,
          "state": "Ready"
      },
      "vector_type": "dense",
      "dimension": 1536,
      "deletion_protection": "disabled",
      "tags": {
          "environment": "development"
      }
  }]
  ```

  ```javascript JavaScript theme={null}
  {
    indexes: [
      {
        name: 'docs-example-sparse',
        dimension: undefined,
        metric: 'dotproduct',
        host: 'docs-example-sparse-govk0nt.svc.aped-4627-b74a.pinecone.io',
        deletionProtection: 'disabled',
        tags: { environment: 'development', example: 'tag' },
        embed: undefined,
        spec: { pod: undefined, serverless: { cloud: 'aws', region: 'us-east-1' } },
        status: { ready: true, state: 'Ready' },
        vectorType: 'sparse'
      },
      {
        name: 'docs-example-dense',
        dimension: 1536,
        metric: 'cosine',
        host: 'docs-example-dense-govk0nt.svc.aped-4627-b74a.pinecone.io',
        deletionProtection: 'disabled',
        tags: { environment: 'development', example: 'tag' },
        embed: undefined,
        spec: { pod: undefined, serverless: { cloud: 'aws', region: 'us-east-1' } },
        status: { ready: true, state: 'Ready' },
        vectorType: 'dense'
      }
    ]
  }
  ```

  ```java Java theme={null}
  class IndexList {
      indexes: [class IndexModel {
          name: docs-example-sparse
          dimension: null
          metric: dotproduct
          host: docs-example-sparse-govk0nt.svc.aped-4627-b74a.pinecone.io
          deletionProtection: disabled
          tags: {environment=development}
          embed: null
          spec: class IndexModelSpec {
              pod: null
              serverless: class ServerlessSpec {
                  cloud: aws
                  region: us-east-1
                  additionalProperties: null
              }
              additionalProperties: null
          }
          status: class IndexModelStatus {
              ready: true
              state: Ready
              additionalProperties: null
          }
          vectorType: sparse
          additionalProperties: null
      }, class IndexModel {
          name: docs-example-dense
          dimension: 1536
          metric: cosine
          host: docs-example-dense-govk0nt.svc.aped-4627-b74a.pinecone.io
          deletionProtection: disabled
          tags: {environment=development}
          embed: null
          spec: class IndexModelSpec {
              pod: null
              serverless: class ServerlessSpec {
                  cloud: aws
                  region: us-east-1
                  additionalProperties: null
              }
              additionalProperties: null
          }
          status: class IndexModelStatus {
              ready: true
              state: Ready
              additionalProperties: null
          }
          vectorType: dense
          additionalProperties: null
      }]
      additionalProperties: null
  }
  ```

  ```go Go theme={null}
  index: {
    "name": "docs-example-sparse",
    "host": "docs-example-sparse-govk0nt.svc.aped-4627-b74a.pinecone.io",
    "metric": "dotproduct",
    "vector_type": "sparse",
    "deletion_protection": "disabled",
    "dimension": null,
    "spec": {
      "serverless": {
        "cloud": "aws",
        "region": "us-east-1"
      }
    },
    "status": {
      "ready": true,
      "state": "Ready"
    },
    "tags": {
      "environment": "development"
    }
  }
  index: {
    "name": "docs-example-dense",
    "host": "docs-example-dense-govk0nt.svc.aped-4627-b74a.pinecone.io",
    "metric": "cosine",
    "vector_type": "dense",
    "deletion_protection": "disabled",
    "dimension": 1536,
    "spec": {
      "serverless": {
        "cloud": "aws",
        "region": "us-east-1"
      }
    },
    "status": {
      "ready": true,
      "state": "Ready"
    },
    "tags": {
      "environment": "development"
    }
  }
  ```

  ```json curl theme={null}
  {
    "indexes": [
      {
        "name": "docs-example-sparse",
        "vector_type": "sparse",
        "metric": "dotproduct",
        "dimension": null,
        "status": {
          "ready": true,
          "state": "Ready"
        },
        "host": "docs-example-sparse-govk0nt.svc.aped-4627-b74a.pinecone.io",
        "spec": {
          "serverless": {
            "region": "us-east-1",
            "cloud": "aws"
          }
        },
        "deletion_protection": "disabled",
        "tags": {
          "environment": "development"
        }
      },
      {
        "name": "docs-example-dense",
        "vector_type": "dense",
        "metric": "cosine",
        "dimension": 1536,
        "status": {
          "ready": true,
          "state": "Ready"
        },
        "host": "docs-example-dense-govk0nt.svc.aped-4627-b74a.pinecone.io",
        "spec": {
          "serverless": {
            "region": "us-east-1",
            "cloud": "aws"
          }
        },
        "deletion_protection": "disabled",
        "tags": {
          "environment": "development"
        }
      }
    ]
  }
  ```
</CodeGroup>

With the Python SDK, you can use the `.names()` helper function to iterate over the index names in the `list_indexes()` response, for example:

```Python Python theme={null}
from pinecone.grpc import PineconeGRPC as Pinecone
from pinecone import ServerlessSpec

for index_name in pc.list_indexes().names:
    print(index_name)
```

## Describe an index

Use the [`describe_index`](/reference/api/latest/control-plane/describe_index/) endpoint to get a complete description of a specific index:

<CodeGroup>
  ```Python Python theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")

  pc.describe_index(name="docs-example")
  ```

  ```JavaScript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone';

  const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' });

  await pc.describeIndex('docs-example');
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Pinecone;
  import org.openapitools.db_control.client.model.*;

  public class DescribeIndexExample {
      public static void main(String[] args) {
          Pinecone pc = new Pinecone.Builder("YOURE_API_KEY").build();
          IndexModel indexModel = pc.describeIndex("docs-example");
          System.out.println(indexModel);
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "encoding/json"
      "fmt"
      "log"

      "github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func prettifyStruct(obj interface{}) string {
      bytes, _ := json.MarshalIndent(obj, "", "  ")
      return string(bytes)
  }

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

      idx, err := pc.DescribeIndex(ctx, "docs-example")
      if err != nil {
          log.Fatalf("Failed to describe index \"%v\": %v", idx.Name, err)
      } else {
          fmt.Printf("index: %v\n", prettifyStruct(idx))
      }
  }
  ```

  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"

  curl -i -X GET "https://api.pinecone.io/indexes/docs-example" \
      -H "Api-Key: $PINECONE_API_KEY" \
      -H "X-Pinecone-Api-Version: 2025-10"
  ```
</CodeGroup>

The response will look like this:

<CodeGroup>
  ```Python Python theme={null}
  {'deletion_protection': 'disabled',
   'dimension': 1536,
   'host': 'docs-example-dense-govk0nt.svc.aped-4627-b74a.pinecone.io',
   'metric': 'cosine',
   'name': 'docs-example-dense',
   'spec': {'serverless': {'cloud': 'aws', 'region': 'us-east-1'}},
   'status': {'ready': True, 'state': 'Ready'},
   'tags': {'environment': 'development'},
   'vector_type': 'dense'}
  ```

  ```javaScript JavaScript theme={null}
  {
    name: 'docs-example-dense',
    dimension: 1536,
    metric: 'cosine',
    host: 'docs-example-dense-govk0nt.svc.aped-4627-b74a.pinecone.io',
    deletionProtection: 'disabled',
    tags: { environment: 'development', example: 'tag' },
    embed: undefined,
    spec: { pod: undefined, serverless: { cloud: 'aws', region: 'us-east-1' } },
    status: { ready: true, state: 'Ready' },
    vectorType: 'dense'
  }
  ```

  ```java Java theme={null}
  class IndexModel {
      name: docs-example-dense
      dimension: 1536
      metric: cosine
      host: docs-example-dense-govk0nt.svc.aped-4627-b74a.pinecone.io
      deletionProtection: disabled
      tags: {environment=development}
      embed: null
      spec: class IndexModelSpec {
          pod: null
          serverless: class ServerlessSpec {
              cloud: aws
              region: us-east-1
              additionalProperties: null
          }
          additionalProperties: null
      }
      status: class IndexModelStatus {
          ready: true
          state: Ready
          additionalProperties: null
      }
      vectorType: dense
      additionalProperties: null
  }
  ```

  ```go Go theme={null}
  index: {
    "name": "docs-example-dense",
    "host": "docs-example-dense-govk0nt.svc.aped-4627-b74a.pinecone.io",
    "metric": "cosine",
    "vector_type": "dense",
    "deletion_protection": "disabled",
    "dimension": 1536,
    "spec": {
      "serverless": {
        "cloud": "aws",
        "region": "us-east-1"
      }
    },
    "status": {
      "ready": true,
      "state": "Ready"
    },
    "tags": {
      "environment": "development"
    }
  }
  ```

  ```json curl theme={null}
  {
    "name": "docs-example-dense",
    "vector_type": "dense",
    "metric": "cosine",
    "dimension": 1536,
    "status": {
      "ready": true,
      "state": "Ready"
    },
    "host": "docs-example-dense-govk0nt.svc.aped-4627-b74a.pinecone.io",
    "spec": {
      "serverless": {
        "region": "us-east-1",
        "cloud": "aws"
      }
    },
    "deletion_protection": "disabled",
    "tags": {
      "environment": "development"
    }
  }
  ```
</CodeGroup>

<Warning>
  **Do not target an index by name in production.**

  When you target an index by name for data operations such as `upsert` and `query`, the SDK gets the unique DNS host for the index using the `describe_index` operation. This is convenient for testing but should be avoided in production because `describe_index` uses a different API than data operations and therefore adds an additional network call and point of failure. Instead, you should get an index host once and cache it for reuse or specify the host directly.
</Warning>

## Delete an index

Use the [`delete_index`](reference/api/latest/control-plane/delete_index) operation to delete an index and all of its associated resources.

<CodeGroup>
  ```python Python theme={null}
  # pip install "pinecone[grpc]"
  from pinecone.grpc import PineconeGRPC as Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")

  pc.delete_index(name="docs-example")
  ```

  ```javascript JavaScript theme={null}
  // npm install @pinecone-database/pinecone
  import { Pinecone } from '@pinecone-database/pinecone'

  const pc = new Pinecone({
    apiKey: 'YOUR_API_KEY'
  });

  await pc.deleteIndex('docs-example');
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Pinecone;

  public class DeleteIndexExample {
      public static void main(String[] args) {
          Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build();
          pc.deleteIndex("docs-example");
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "fmt"
      "log"

      "github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

      indexName := "docs-example"

      err = pc.DeleteIndex(ctx, indexName)
      if err != nil {
          log.Fatalf("Failed to delete index: %v", err)
      } else {
          fmt.Println("Index \"%v\" deleted successfully", indexName)
      }
  }
  ```

  ```shell curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"

  curl -i -X DELETE "https://api.pinecone.io/indexes/docs-example" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2025-10"
  ```
</CodeGroup>

If deletion protection is enabled on an index, requests to delete it will fail and return a `403 - FORBIDDEN` status with the following error:

```
Deletion protection is enabled for this index. Disable deletion protection before retrying.
```

Before you can delete such an index, you must first [disable deletion protection](/guides/manage-data/manage-indexes#configure-deletion-protection).

<Tip>
  You can delete an index using the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/indexes). For the index you want to delete, click the three dots to the right of the index name, then click **Delete**.
</Tip>

## Associate an embedding model

[Integrated inference](/guides/index-data/indexing-overview#integrated-embedding) lets you upsert and search without extra steps for embedding data and reranking results.

To configure an existing serverless index for an embedding model, use the [`configure_index`](/reference/api/latest/control-plane/configure_index) operation as follows:

* Set `embed.model` to one of [Pinecone's hosted embedding models](/guides/index-data/create-an-index#embedding-models).
* Set `embed.field_map` to the name of the field in your source document that contains the data for embedding.

<Warning>
  The `vector_type`, `metric`, and `dimension` of the index must be supported by the specified embedding model.
</Warning>

<CodeGroup>
  ```python Python theme={null}
  # pip install --upgrade pinecone
  from pinecone import Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")

  pc.configure_index(
      name="docs-example",
      embed={
        "model":"llama-text-embed-v2",
        "field_map":{"text": "chunk_text"}
      }
  )
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone';

  const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' });

  await pc.configureIndex('docs-example', {
    embed: {
      model: 'llama-text-embed-v2',
      fieldMap: { text: 'chunk_text' },
    },
  });
  ```

  ```json curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"

  curl -s -X PATCH "https://api.pinecone.io/indexes/docs-example" \
      -H "Content-Type: application/json" \
      -H "Api-Key: $PINECONE_API_KEY" \
      -H "X-Pinecone-Api-Version: 2025-10" \
      -d '{
        "embed": {
            "model": "llama-text-embed-v2",
            "field_map": {
                "text": "chunk_text"
            }
        }
    }'
  ```
</CodeGroup>

## Configure deletion protection

<Note>
  This feature requires [Pinecone API version](/reference/api/versioning) `2024-07`, [Python SDK](/reference/sdks/python/overview) v5.0.0, [Node.js SDK](/reference/sdks/node/overview) v3.0.0, [Java SDK](/reference/sdks/java/overview) v2.0.0, or [Go SDK](/reference/sdks/go/overview) v1.0.0 or later.
</Note>

### Enable deletion protection

You can prevent an index and its data from accidental deleting when [creating a new index](/guides/index-data/create-an-index) or after its been created. In both cases, you set the `deletion_protection` parameter to `enabled`.

<Warning>
  Enabling deletion protection does *not* prevent [namespace deletions](/guides/manage-data/manage-namespaces#delete-a-namespace).
</Warning>

To enable deletion protection when creating a new index:

<CodeGroup>
  ```python Python theme={null}
  # pip install "pinecone[grpc]"
  # Serverless index
  from pinecone.grpc import PineconeGRPC as Pinecone
  from pinecone import ServerlessSpec

  pc = Pinecone(api_key="YOUR_API_KEY")

  pc.create_index(
    name="docs-example",
    dimension=1536,
    metric="cosine",
    spec=ServerlessSpec(
      cloud="aws",
      region="us-east-1"
    ),
    deletion_protection="enabled"
  )
  ```

  ```javascript JavaScript theme={null}
  // npm install @pinecone-database/pinecone
  // Serverles index
  import { Pinecone } from '@pinecone-database/pinecone'

  const pc = new Pinecone({
    apiKey: 'YOUR_API_KEY'
  });

  await pc.createIndex({
    name: 'docs-example',
    dimension: 1536,
    metric: 'cosine',
    spec: {
      serverless: {
        cloud: 'aws',
        region: 'us-east-1'
      }
    },
    deletionProtection: 'enabled',
  });
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Pinecone;
  import org.openapitools.db_control.client.model.IndexModel;
  import org.openapitools.db_control.client.model.DeletionProtection;

  // Serverless index
  public class CreateServerlessIndexExample {
      public static void main(String[] args) {
          Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build();
          pc.createServerlessIndex("docs-example", "cosine", 1536, "aws", "us-east-1", DeletionProtection.enabled);
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "fmt"
      "log"

      "github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

      // Serverless index
    	indexName := "docs-example"
  	vectorType := "dense"
      dimension := int32(1536)
      metric := pinecone.Cosine
  	deletionProtection := pinecone.DeletionProtectionDisabled

  	idx, err := pc.CreateServerlessIndex(ctx, &pinecone.CreateServerlessIndexRequest{
          Name:               indexName,
          VectorType:         &vectorType,
          Dimension:          &dimension,
          Metric:             &metric,
          Cloud:              pinecone.Aws,
          Region:             "us-east-1",
          DeletionProtection: &deletionProtection,
          Tags:               &pinecone.IndexTags{ "environment": "development" },
      })
      if err != nil {
          log.Fatalf("Failed to create serverless index: %v", err)
      } else {
          fmt.Printf("Successfully created serverless index: %v", idx.Name)
      }
  }
  ```

  ```shell curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"

  # Serverless index
  curl -s "https://api.pinecone.io/indexes" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2025-10" \
    -d '{
           "name": "docs-example",
           "dimension": 1536,
           "metric": "cosine",
           "spec": {
              "serverless": {
                 "cloud": "aws",
                 "region": "us-east-1"
              }
           },
           "deletion_protection": "enabled"
        }'
  ```
</CodeGroup>

To enable deletion protection when configuring an existing index:

<CodeGroup>
  ```python Python theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")

  pc.configure_index(
     name="docs-example", 
     deletion_protection="enabled"
  )
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone';

  const client = new Pinecone({ apiKey: 'YOUR_API_KEY' });

  await client.configureIndex('docs-example', { deletionProtection: 'enabled' });
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Pinecone;
  import org.openapitools.db_control.client.model.*;

  public class ConfigureIndexExample {
      public static void main(String[] args) {
          Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build();
          pc.configureServerlessIndex("docs-example", DeletionProtection.ENABLED);
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "fmt"
      "log"

      "github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

      idx, err := pc.ConfigureIndex(ctx, "docs-example", pinecone.ConfigureIndexParams{DeletionProtection: "enabled"})
    	if err != nil {
          log.Fatalf("Failed to configure index \"%v\": %v", idx.Name, err)
      } else {
          fmt.Printf("Successfully configured index \"%v\"", idx.Name)
      }
  }
  ```

  ```shell curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"

  curl -s -X PATCH "https://api.pinecone.io/indexes/docs-example-curl" \
      -H "Content-Type: application/json" \
      -H "Api-Key: $PINECONE_API_KEY" \
      -H "X-Pinecone-Api-Version: 2025-10" \
      -d '{
          "deletion_protection": "enabled"
          }'
  ```
</CodeGroup>

When deletion protection is enabled on an index, requests to delete the index fail and return a `403 - FORBIDDEN` status with the following error:

```
Deletion protection is enabled for this index. Disable deletion protection before retrying.
```

### Disable deletion protection

Before you can [delete an index](#delete-an-index) with deletion protection enabled, you must first disable deletion protection as follows:

<CodeGroup>
  ```python Python theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")

  pc.configure_index(
     name="docs-example", 
     deletion_protection="disabled"
  )
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone';

  const client = new Pinecone({ apiKey: 'YOUR_API_KEY' });

  await client.configureIndex('docs-example', { deletionProtection: 'disabled' });
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Pinecone;
  import org.openapitools.db_control.client.model.*;

  public class ConfigureIndexExample {
      public static void main(String[] args) {
          Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build();
          pc.configureServerlessIndex("docs-example", DeletionProtection.DISABLED);
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "fmt"
      "log"

      "github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

      idx, err := pc.ConfigureIndex(ctx, "docs-example", pinecone.ConfigureIndexParams{DeletionProtection: "disabled"})
    	if err != nil {
          log.Fatalf("Failed to configure index \"%v\": %v", idx.Name, err)
      } else {
          fmt.Printf("Successfully configured index \"%v\"", idx.Name)
      }
  }
  ```

  ```shell curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"

  curl -s -X PATCH "https://api.pinecone.io/indexes/docs-example-curl" \
      -H "Content-Type: application/json" \
      -H "Api-Key: $PINECONE_API_KEY" \
      -H "X-Pinecone-Api-Version: 2025-10" \
      -d '{
          "deletion_protection": "disabled"
          }'
  ```
</CodeGroup>

## Configure index tags

Tags are key-value pairs that you can use to categorize and identify the index.

### Add tags

To add tags to an index, use the `tags` parameter when [creating a new index](/guides/index-data/create-an-index) or configuring an existing index.

To add tags when creating a new index:

<CodeGroup>
  ```python Python theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone
  from pinecone import ServerlessSpec

  pc = Pinecone(api_key="YOUR_API_KEY")

  pc.create_index(
      name="docs-example",
      dimension=1536,
      metric="cosine",
      spec=ServerlessSpec(
          cloud="aws",
          region="us-east-1"
      ),
      deletion_protection="disabled",
      tags={
          "example": "tag", 
          "environment": "development"
      }
  )
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone'

  const client = new Pinecone({ apiKey: 'YOUR_API_KEY' });

  await pc.createIndex({
    name: 'docs-example',
    dimension: 1536,
    metric: 'cosine',
    spec: {
      serverless: {
        cloud: 'aws',
        region: 'us-east-1'
      }
    },
    deletionProtection: 'disabled',
    tags: { example: 'tag', environment: 'development' }, 
  });
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Pinecone;
  import org.openapitools.db_control.client.model.IndexModel;
  import org.openapitools.db_control.client.model.DeletionProtection;
  import java.util.HashMap;

  // Serverless index
  public class CreateServerlessIndexExample {
      public static void main(String[] args) {
          Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build();
          HashMap<String, String> tags = new HashMap<>();
          tags.put("tag", "development");
          pc.createServerlessIndex("docs-example", "cosine", 1536, "aws", "us-east-1", DeletionProtection.DISABLED, tags);
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "fmt"
      "log"

      "github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

      // Serverless index
      idx, err := pc.CreateServerlessIndex(ctx, &pinecone.CreateServerlessIndexRequest{
          Name:               "docs-example",
          Dimension:          1536,
          Metric:             pinecone.Cosine,
          Cloud:              pinecone.Aws,
          Region:             "us-east-1",
          DeletionProtection: "disabled",
          Tags:               &pinecone.IndexTags{ "example": "tag", "environment": "development" },
      })
    	if err != nil {
          log.Fatalf("Failed to create serverless index: %v", err)
      } else {
          fmt.Printf("Successfully created serverless index: %v", idx.Name)
      }
  }
  ```

  ```shell curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"

  # Serverless index
  curl -s "https://api.pinecone.io/indexes" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2025-10" \
    -d '{
           "name": "docs-example",
           "dimension": 1536,
           "metric": "cosine",
           "spec": {
              "serverless": {
                 "cloud": "aws",
                 "region": "us-east-1"
              }
           },
          "tags": {
              "example": "tag",
              "environment": "development"
          },
           "deletion_protection": "disabled"
        }'
  ```
</CodeGroup>

<Tip>
  You can add tags during index creation using the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/create-index/).
</Tip>

To add or update tags when configuring an existing index:

<CodeGroup>
  ```python Python theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")

  pc.configure_index(
      name="docs-example", 
      tags={
          example: "tag", 
          environment: "development" 
      }
  )
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone';

  const client = new Pinecone({ apiKey: 'YOUR_API_KEY' });

  await client.configureIndex('docs-example', { tags: { example: 'tag', environment: 'development' }});
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Pinecone;
  import org.openapitools.db_control.client.model.*;
  import java.util.HashMap;

  public class ConfigureIndexExample {
      public static void main(String[] args) {
          Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build();
          HashMap<String, String> tags = new HashMap<>();
          tags.put("tag", "development");

          pc.configureServerlessIndex("docs-example", DeletionProtection.ENABLED, tags);
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "fmt"
      "log"

      "github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

      idx, err := pc.ConfigureIndex(ctx, 
          "docs-example", 
          pinecone.ConfigureIndexParams{
              Tags: pinecone.IndexTags{
  			    "example": "tag",
                  "environment": "development",
              },
          },
      )    
    	if err != nil {
          log.Fatalf("Failed to configure index \"%v\": %v", idx.Name, err)
      } else {
          fmt.Printf("Successfully configured index \"%v\"", idx.Name)
      }
  }
  ```

  ```shell curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"

  curl -s -X PATCH "https://api.pinecone.io/indexes/docs-example-curl" \
      -H "Content-Type: application/json" \
      -H "Api-Key: $PINECONE_API_KEY" \
      -H "X-Pinecone-Api-Version: 2025-10" \
      -d '{
              "tags": {
                  "example": "tag",
                  "environment": "development"
              }
          }'
  ```
</CodeGroup>

<Tip>
  You can add or update tags when configuring an existing index using the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/indexes). Find the index to edit and click the **ellipsis (...) menu > Add tags**.
</Tip>

### View tags

To view the tags of an index, [list all indexes](/guides/manage-data/manage-indexes) in a project or [get information about a specific index](/guides/manage-data/manage-indexes).

### Remove tags

To remove a tag from an index, [configure the index](/reference/api/latest/control-plane/configure_index) and use the `tags` parameter to send the tag key with an empty value (`""`).

The following example removes the `example: tag` tag from `docs-example`:

<CodeGroup>
  ```python Python theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")

  pc.configure_index(
      name="docs-example", 
      tags={"example": ""}
  )
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone';

  const client = new Pinecone({ apiKey: 'YOUR_API_KEY' });

  await client.configureIndex('docs-example', { tags: { example: '' }});
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Pinecone;
  import org.openapitools.db_control.client.model.*;
  import java.util.HashMap;

  public class ConfigureIndexExample {
      public static void main(String[] args) {
          Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build();
          HashMap<String, String> tags = new HashMap<>();
          tags.put("example", "");

          pc.configureServerlessIndex("docs-example", DeletionProtection.ENABLED, tags);
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "fmt"
      "log"

      "github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

      idx, err := pc.ConfigureIndex(ctx, 
          "docs-example", 
          pinecone.ConfigureIndexParams{
              Tags: pinecone.IndexTags{
  			    "example": "",
              },
          },
      )    
    	if err != nil {
          log.Fatalf("Failed to configure index \"%v\": %v", idx.Name, err)
      } else {
          fmt.Printf("Successfully configured index \"%v\"", idx.Name)
      }
  }
  ```

  ```shell curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"

  curl -s -X PATCH "https://api.pinecone.io/indexes/docs-example-curl" \
      -H "Content-Type: application/json" \
      -H "Api-Key: $PINECONE_API_KEY" \
      -H "X-Pinecone-Api-Version: 2025-10" \
      -d '{
              "tags": {
                  "example": ""
              }
          }'
  ```
</CodeGroup>

<Tip>
  You can remove tags from an index using the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/indexes). Find the index to edit and click the **ellipsis (...) menu > \_\_ tags**.
</Tip>

## List backups for an index

Serverless indexes can be [backed up](/guides/manage-data/back-up-an-index). You can [list all backups for a specific index](/reference/api/latest/control-plane/list_index_backups), as in the following example:

<CodeGroup>
  ```python Python theme={null}
  from pinecone import Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")

  index_backups = pc.list_backups(index_name="docs-example")

  print(index_backups)
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone';

  const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' })

  const indexBackups = await pc.listBackups({ indexName: 'docs-example' });

  console.log(indexBackups);
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Pinecone;
  import org.openapitools.db_control.client.ApiException;
  import org.openapitools.db_control.client.model.*;

  public class CreateBackup {
      public static void main(String[] args) throws ApiException {
          Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build();

          String indexName = "docs-example";
          BackupList indexBackupList = pc.listIndexBackups(indexName);

          System.out.println(indexBackupList);
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
  	"context"
  	"encoding/json"
  	"fmt"
  	"log"

  	"github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func prettifyStruct(obj interface{}) string {
  	bytes, _ := json.MarshalIndent(obj, "", "  ")
  	return string(bytes)
  }

  func main() {
  	ctx := context.Background()

  	pc, err := pinecone.NewClient(pinecone.NewClientParams{
  		ApiKey: "YOUR_API_KEY",
  	})
  	if err != nil {
  		log.Fatalf("Failed to create Client: %v", err)
  	}

  	indexName := "docs-example"
  	limit := 2
  	indexBackups, err := pc.ListBackups(ctx, &pinecone.ListBackupsParams{
  		Limit: &limit,
  		IndexName: &indexName,
  	})
  	if err != nil {
  		log.Fatalf("Failed to list backups: %v", err)
  	}
  	fmt.Printf(prettifyStruct(indexBackups))
  }
  ```

  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  INDEX_NAME="docs-example"

  curl -X GET "https://api.pinecone.io/indexes/$INDEX_NAME/backups" \
      -H "Api-Key: $PINECONE_API_KEY" \
      -H "X-Pinecone-Api-Version: 2025-10" \
      -H "accept: application/json"
  ```
</CodeGroup>

The example returns a response like the following:

<CodeGroup>
  ```python Python theme={null}
  [{
      "backup_id": "8c85e612-ed1c-4f97-9f8c-8194e07bcf71",
      "source_index_name": "docs-example",
      "source_index_id": "f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74",
      "status": "Ready",
      "cloud": "aws",
      "region": "us-east-1",
      "tags": {},
      "name": "example-backup",
      "description": "Monthly backup of production index",
      "dimension": 1024,
      "record_count": 98,
      "namespace_count": 3,
      "size_bytes": 1069169,
      "created_at": "2025-05-15T00:52:10.809305882Z"
  }]
  ```

  ```javascript JavaScript theme={null}
  {
    data: [
      {
        backupId: '8c85e612-ed1c-4f97-9f8c-8194e07bcf71',
        sourceIndexName: 'docs-example',
        sourceIndexId: 'f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74',
        name: 'example-backup',
        description: 'Monthly backup of production index',
        status: 'Ready',
        cloud: 'aws',
        region: 'us-east-1',
        dimension: 1024,
        metric: undefined,
        recordCount: 98,
        namespaceCount: 3,
        sizeBytes: 1069169,
        tags: {},
        createdAt: '2025-05-14T16:37:25.625540Z'
      }
    ],
    pagination: undefined
  }
  ```

  ```java Java theme={null}
  class BackupList {
      data: [class BackupModel {
          backupId: 8c85e612-ed1c-4f97-9f8c-8194e07bcf71
          sourceIndexName: docs-example
          sourceIndexId: f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74
          name: example-backup
          description: Monthly backup of production index
          status: Initializing
          cloud: aws
          region: us-east-1
          dimension: null
          metric: null
          recordCount: null
          namespaceCount: null
          sizeBytes: null
          tags: {}
          createdAt: 2025-05-16T19:46:26.248428Z
          additionalProperties: null
      }]
      pagination: null
      additionalProperties: null
  }
  ```

  ```go Go theme={null}
  {
    "data": [
      {
        "backup_id": "bf2cda5d-b233-4a0a-aae9-b592780ad3ff",
        "cloud": "aws",
        "created_at": "2025-05-16T18:01:51.531129Z",
        "description": "Monthly backup of production index",
        "dimension": 0,
        "name": "example-backup",
        "namespace_count": 1,
        "record_count": 96,
        "region": "us-east-1",
        "size_bytes": 86393,
        "source_index_id": "bcb5b3c9-903e-4cb6-8b37-a6072aeb874f",
        "source_index_name": "docs-example",
        "status": "Ready",
        "tags": {}
      },
      {
        "backup_id": "e12269b0-a29b-4af0-9729-c7771dec03e3",
        "cloud": "aws",
        "created_at": "2025-05-14T17:00:45.803146Z",
        "dimension": 0,
        "name": "example-backup2",
        "namespace_count": 1,
        "record_count": 96,
        "region": "us-east-1",
        "size_bytes": 86393,
        "source_index_id": "bcb5b3c9-903e-4cb6-8b37-a6072aeb874f",
        "source_index_name": "docs-example",
        "status": "Ready"
      }
    ],
    "pagination": {
      "next": "eyJsaW1pdCI6Miwib2Zmc2V0IjoyfQ=="
    }
  }
  ```

  ```json curl theme={null}
  {
    "data":
    [
      {
        "backup_id":"9947520e-d5a1-4418-a78d-9f464c9969da",
        "source_index_id":"8433941a-dae7-43b5-ac2c-d3dab4a56b2b",
        "source_index_name":"docs-example",
        "tags":{},
        "name":"example-backup",
        "description":"Monthly backup of production index",
        "status":"Pending",
        "cloud":"aws",
        "region":"us-east-1",
        "dimension":1024,
        "record_count":98,
        "namespace_count":3,
        "size_bytes":1069169,
        "created_at":"2025-03-11T18:29:50.549505Z"
        }
      ],
    "pagination":null
  }
  ```
</CodeGroup>

<Tip>
  You can view the backups for a specific index from either the [Backups](https://app.pinecone.io/organizations/-/projects/-/backups) tab or the [Indexes](https://app.pinecone.io/organizations/-/projects/-/indexes) tab in the Pinecone console.
</Tip>


# Manage namespaces
Source: https://docs.pinecone.io/guides/manage-data/manage-namespaces

Create, describe, list, and delete namespaces in Pinecone serverless indexes, including defining filterable metadata fields and schemas ahead of upsert.

## Create a namespace

<Note>
  This feature is available only on the `2025-10` version of the API.
</Note>

Namespaces are created automatically as you [upsert](/guides/index-data/upsert-data) records. However, you can also create namespaces ahead of time using the [`create_namespace`](/reference/api/2025-10/data-plane/createnamespace) operation. Specify a name for the namespace and, optionally, the [metadata fields to index](/guides/index-data/create-an-index#metadata-indexing).

<CodeGroup>
  ```python Python theme={null}
  from pinecone import Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")

  # To get the unique host for an index, 
  # see https://docs.pinecone.io/guides/manage-data/target-an-index
  index = pc.Index(host="INDEX_HOST")

  namespace = index.create_namespace(
      name="example-namespace",
      schema={
          "fields": {
              "document_id": {"filterable": True},
              "document_title": {"filterable": True},
              "chunk_number": {"filterable": True},
              "document_url": {"filterable": True},
              "created_at": {"filterable": True}
          }
      }
  )

  print(namespace)
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone';

  const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' })

  // To get the unique host for an index, 
  // see https://docs.pinecone.io/guides/manage-data/target-an-index
  const index = pc.index('INDEX_NAME', 'INDEX_HOST');

  const namespace = await index.createNamespace({
    name: 'example-namespace',
    schema: {
      fields: {
        document_id: { filterable: true },
        document_title: { filterable: true },
        chunk_number: { filterable: true },
        document_url: { filterable: true },
        created_at: { filterable: true }
      }
    }
  });

  console.log(namespace);
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Index;
  import io.pinecone.configs.PineconeConfig;
  import io.pinecone.configs.PineconeConnection;
  import io.pinecone.proto.NamespaceDescription;
  import io.pinecone.proto.MetadataSchema;
  import io.pinecone.proto.MetadataSchemaField;

  public class CreateNamespaceExample {
      public static void main(String[] args) {
          PineconeConfig config = new PineconeConfig("YOUR_API_KEY");
          // To get the unique host for an index, 
          // see https://docs.pinecone.io/guides/manage-data/target-an-index
          config.setHost("INDEX_HOST");
          PineconeConnection connection = new PineconeConnection(config);

          Index index = new Index(config, connection, "INDEX_NAME");

          MetadataSchemaField filterable = MetadataSchemaField.newBuilder()
              .setFilterable(true)
              .build();

          MetadataSchema schema = MetadataSchema.newBuilder()
              .putFields("document_id", filterable)
              .putFields("document_title", filterable)
              .putFields("chunk_number", filterable)
              .putFields("document_url", filterable)
              .putFields("created_at", filterable)
              .build();

          NamespaceDescription namespace = index.createNamespace("example-namespace", schema);

          System.out.println(namespace);
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "encoding/json"
      "fmt"
      "log"

      "github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func prettifyStruct(obj interface{}) string {
    	bytes, _ := json.MarshalIndent(obj, "", "  ")
      return string(bytes)
  }

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

      // To get the unique host for an index, 
      // see https://docs.pinecone.io/guides/manage-data/target-an-index
      idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST"})
      if err != nil {
          log.Fatalf("Failed to create IndexConnection for Host: %v", err)
      } 

      namespace, err := idxConnection.CreateNamespace(ctx, &pinecone.CreateNamespaceParams{
          Name: "example-namespace",
          Schema: &pinecone.MetadataSchema{
              Fields: map[string]pinecone.MetadataSchemaField{
                  "document_id":    {Filterable: true},
                  "document_title": {Filterable: true},
                  "chunk_number":   {Filterable: true},
                  "document_url":   {Filterable: true},
                  "created_at":     {Filterable: true},
              },
          },
      })
      if err != nil {
          log.Fatalf("Failed to create namespace: %v", err)
      }
      fmt.Printf(prettifyStruct(namespace))
  }
  ```

  ```shell curl theme={null}
  # To get the unique host for an index,
  # see https://docs.pinecone.io/guides/manage-data/target-an-index
  PINECONE_API_KEY="YOUR_API_KEY"
  INDEX_HOST="INDEX_HOST"

  curl "https://$INDEX_HOST/namespaces" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2025-10" \
    -d '{
          "name": "example-namespace",
          "schema": {
            "fields": { 
              "document_id": {"filterable": true},
              "document_title": {"filterable": true},
              "chunk_number": {"filterable": true},
              "document_url": {"filterable": true},
              "created_at": {"filterable": true}
            }
          }
        }'
  ```
</CodeGroup>

The response will look like the following:

```json theme={null}
{
    "name": "example-namespace",
    "record_count": "0",
    "schema": {
        "fields": {
            "document_title": {
                "filterable": true
            },
            "document_url": {
                "filterable": true
            },
            "chunk_number": {
                "filterable": true
            },
            "document_id": {
                "filterable": true
            },
            "created_at": {
                "filterable": true
            }
        }
    }
}
```

## List all namespaces in an index

Use the [`list_namespaces`](/reference/api/latest/data-plane/listnamespaces) operation to list all namespaces in a serverless index.

Up to 100 namespaces are returned at a time by default, in sorted order (bitwise “C” collation). If the `limit` parameter is set, up to that number of namespaces are returned instead. Whenever there are additional namespaces to return, the response also includes a `pagination_token` that you can use to get the next batch of namespaces. When the response does not include a `pagination_token`, there are no more namespaces to return.

<CodeGroup>
  ```python Python theme={null}
  # Not supported with pinecone["grpc"] extras installed
  from pinecone import Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")

  index = pc.Index(host="INDEX_HOST")

  # Implicit pagination using a generator function
  for namespace in index.list_namespaces():
      print(namespace.name, ":", namespace.record_count)

  # Manual pagination
  namespaces = index.list_namespaces_paginated(
      limit=2,
      pagination_token="eyJza2lwX3Bhc3QiOiIxMDEwMy0="
  )

  print(namespaces)
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone';

  const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' })

  // To get the unique host for an index, 
  // see https://docs.pinecone.io/guides/manage-data/target-an-index
  var index = pinecone.Index(host: "INDEX_HOST");

  const namespaceList = await index.listNamespaces();

  console.log(namespaceList);
  ```

  ```java Java theme={null}
  import io.pinecone.clients.AsyncIndex;
  import io.pinecone.clients.Index;
  import io.pinecone.configs.PineconeConfig;
  import io.pinecone.configs.PineconeConnection;
  import io.pinecone.proto.ListNamespacesResponse;
  import org.openapitools.db_data.client.ApiException;

  public class Namespaces {
      public static void main(String[] args) throws ApiException {
          PineconeConfig config = new PineconeConfig("YOUR_API_KEY");
          // To get the unique host for an index, 
          // see https://docs.pinecone.io/guides/manage-data/target-an-index
          config.setHost("INDEX_HOST");
          PineconeConnection connection = new PineconeConnection(config);

          Index index = new Index(config, connection, "docs-example");

          // List all namespaces with default pagination limit (100)
          ListNamespacesResponse listNamespacesResponse = index.listNamespaces(null, null);

          // List all namespaces with pagination limit of 2
          ListNamespacesResponse listNamespacesResponseWithLimit = index.listNamespaces(2);

          // List all namespaces with pagination limit and token
          ListNamespacesResponse listNamespacesResponsePaginated = index.listNamespaces(5, "eyJza2lwX3Bhc3QiOiIxMDEwMy0=");

          System.out.println(listNamespacesResponseWithLimit);
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "encoding/json"
      "fmt"
      "log"

      "github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func prettifyStruct(obj interface{}) string {
    	bytes, _ := json.MarshalIndent(obj, "", "  ")
      return string(bytes)
  }

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

      // To get the unique host for an index, 
      // see https://docs.pinecone.io/guides/manage-data/target-an-index
      idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST"})
      if err != nil {
          log.Fatalf("Failed to create IndexConnection for Host: %v", err)
      } 

      limit := uint32(10)
      namespaces, err := idxConnection.ListNamespaces(ctx, &pinecone.ListNamespacesParams{
          Limit: &limit,
      })
      if err != nil {
          log.Fatalf("Failed to list namespaces: %v", err)
      }
      fmt.Printf(prettifyStruct(namespaces))
  }
  ```

  ```shell curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  INDEX_HOST="INDEX_HOST"

  curl -X GET "https://$INDEX_HOST/namespaces" \
      -H "Api-Key: $PINECONE_API_KEY" \
      -H "X-Pinecone-Api-Version: 2025-10"
  ```
</CodeGroup>

The response will look like the following:

<CodeGroup>
  ```plaintext Python theme={null}
  # Implicit pagination (print output from: for n in index.list_namespaces(): print(n.name, ":", n.record_count))
  example-namespace : 20000
  example-namespace2 : 10500
  example-namespace3 : 10000
  ...

  # Manual pagination (response from list_namespaces_paginated())
  {
      "namespaces": [
          {"name": "example-namespace", "record_count": "20000"},
          {"name": "example-namespace2", "record_count": "10500"}
      ],
      "pagination": {"next": "Tm90aGluZyB0byBzZWUgaGVyZQo="}
  }
  ```

  ```javascript JavaScript theme={null}
  {
    namespaces: [
      { name: 'example-namespace', recordCount: '20000' },
      { name: 'example-namespace2', recordCount: '10500' },
      ...
    ],
    pagination: "Tm90aGluZyB0byBzZWUgaGVyZQo="
  }
  ```

  ```java Java theme={null}
  namespaces {
    name: "example-namespace"
    record_count: 20000
  }
  namespaces {
    name: "example-namespace2"
    record_count: 10500
  }
  pagination {
    next: "eyJza2lwX3Bhc3QiOiJlZDVhYzFiNi1kMDFiLTQ2NTgtYWVhZS1hYjJkMGI2YzBiZjQiLCJwcmVmaXgiOm51bGx9"
  }
  ```

  ```go Go theme={null}
  {
    "Namespaces": [
      {
        "name": "example-namespace",
        "record_count": 20000
      },
      {
        "name": "example-namespace2",
        "record_count": 10500
      },
      ...
    ],
    "Pagination": {
      "next": "eyJza2lwX3Bhc3QiOiIyNzQ5YTU1YS0zZTQ2LTQ4MDItOGFlNi1hZTJjZGNkMTE5N2IiLCJwcmVmaXgiOm51bGx9"
    }
  }
  ```

  ```json curl theme={null}
  {
    "namespaces": [
      {
        "name": "example-namespace",
        "record_count": 20000
      },
      {
        "name": "example-namespace2",
        "record_count": 10500
      },
      ...
    ],
    "pagination": {
      "next": "Tm90aGluZyB0byBzZWUgaGVyZQo="
    }
  }
  ```
</CodeGroup>

## Describe a namespace

Use the [`describe_namespace`](/reference/api/latest/data-plane/describenamespace) operation to get details about a namespace in a serverless index, including the total number of vectors in the namespace.

<CodeGroup>
  ```python Python theme={null}
  # Not supported with pinecone["grpc"] extras installed
  from pinecone import Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")

  index = pc.Index(host="INDEX_HOST")

  namespace = index.describe_namespace(namespace="example-namespace")

  print(namespace)
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone';

  const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' })

  const index = pc.index('docs-example');

  const namespace = await index.describeNamespace('example-namespace');

  console.log(namespace);
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Index;
  import io.pinecone.configs.PineconeConfig;
  import io.pinecone.configs.PineconeConnection;
  import io.pinecone.proto.NamespaceDescription;

  import org.openapitools.db_data.client.ApiException;

  public class Namespaces {
      public static void main(String[] args) throws ApiException {
          PineconeConfig config = new PineconeConfig("YOUR_API_KEY");
          // To get the unique host for an index, 
          // see https://docs.pinecone.io/guides/manage-data/target-an-index
          config.setHost("INDEX_HOST");
          PineconeConnection connection = new PineconeConnection(config);

          Index index = new Index(config, connection, "docs-example");

          NamespaceDescription namespaceDescription = index.describeNamespace("example-namespace");

          System.out.println(namespaceDescription);
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "encoding/json"
      "fmt"
      "log"

      "github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func prettifyStruct(obj interface{}) string {
    	bytes, _ := json.MarshalIndent(obj, "", "  ")
      return string(bytes)
  }

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

      // To get the unique host for an index, 
      // see https://docs.pinecone.io/guides/manage-data/target-an-index
      idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST"})
      if err != nil {
          log.Fatalf("Failed to create IndexConnection for Host: %v", err)
      } 

      namespace, err := idxConnection.DescribeNamespace(ctx, "example-namespace")
      if err != nil {
          log.Fatalf("Failed to describe namespace: %v", err)
      }
      fmt.Printf(prettifyStruct(namespace))
  }
  ```

  ```shell curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  INDEX_HOST="INDEX_HOST"
  NAMESPACE="NAMESPACE_NAME"  # To target the default namespace, use "__default__".

  curl -X GET "https://$INDEX_HOST/namespaces/$NAMESPACE" \
      -H "Api-Key: $PINECONE_API_KEY" \
      -H "X-Pinecone-Api-Version: 2025-10"
  ```
</CodeGroup>

The response will look like the following:

<CodeGroup>
  ```python Python theme={null}
  {
      "name": "example-namespace",
      "record_count": "20000"
  }
  ```

  ```javascript JavaScript theme={null}
  { name: 'example-namespace', recordCount: '20000' }
  ```

  ```java Java theme={null}
  name: "example-namespace"
  record_count: 20000
  ```

  ```go Go theme={null}
  {
    "name": "example-namespace",
    "record_count": 20000
  }
  ```

  ```json curl theme={null}
  {
    "name": "example-namespace",
    "record_count": 20000
  }
  ```
</CodeGroup>

## Delete a namespace

Use the [`delete_namespace`](/reference/api/latest/data-plane/deletenamespace) operation to delete a namespace in a serverless index.

<Warning>
  Deleting a namespace is irreversible. All data in the namespace is permanently deleted.
</Warning>

<CodeGroup>
  ```python Python theme={null}
  # Not supported with pinecone["grpc"] extras installed
  from pinecone import Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")

  index = pc.Index(host="INDEX_HOST")

  index.delete_namespace(namespace="example-namespace")
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone';

  const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' })

  const index = pc.index('INDEX_NAME', 'INDEX_HOST');

  const namespace = await index.deleteNamespace('example-namespace');

  console.log(namespace);
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Index;
  import io.pinecone.configs.PineconeConfig;
  import io.pinecone.configs.PineconeConnection;

  import java.util.concurrent.ExecutionException;

  public class DeleteNamespace {
      public static void main(String[] args) throws ExecutionException, InterruptedException {
          PineconeConfig config = new PineconeConfig("YOUR_API_KEY");
        // To get the unique host for an index, 
        // see https://docs.pinecone.io/guides/manage-data/target-an-index
          config.setHost("INDEX_HOST");
          PineconeConnection connection = new PineconeConnection(config);

          Index index = new Index(config, connection, "docs-example");

          index.deleteNamespace("example-namespace");
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "encoding/json"
      "fmt"
      "log"

      "github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func prettifyStruct(obj interface{}) string {
    	bytes, _ := json.MarshalIndent(obj, "", "  ")
      return string(bytes)
  }

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

      // To get the unique host for an index, 
      // see https://docs.pinecone.io/guides/manage-data/target-an-index
      idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST"})
      if err != nil {
          log.Fatalf("Failed to create IndexConnection for Host: %v", err)
      } 

      err := idxConnection.DeleteNamespace(ctx, "example-namespace")
      if err != nil {
          log.Fatalf("Failed to delete namespace: %v", err)
      }
  }
  ```

  ```shell curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  INDEX_HOST="INDEX_HOST"
  NAMESPACE="NAMESPACE_NAME" # To target the default namespace, use "__default__".

  curl -X DELETE "https://$INDEX_HOST/namespaces/$NAMESPACE" \
      -H "Api-Key: $PINECONE_API_KEY" \
      -H "X-Pinecone-Api-Version: 2025-10"
  ```
</CodeGroup>

## Rename a namespace

Pinecone does not support renaming namespaces directly. Instead, you must [delete the records](/guides/manage-data/delete-data) in the namespace and [upsert the records](/guides/index-data/upsert-data) to a new namespace.

## Move records to a new namespace

Pinecone does not support moving records between namespaces directly. Instead, you must [delete the records](/guides/manage-data/delete-data) in the old namespace and [upsert the records](/guides/index-data/upsert-data) to the new namespace.


# Restore an index
Source: https://docs.pinecone.io/guides/manage-data/restore-an-index

Restore a Pinecone serverless index from a backup, change the index name, tags, or deletion protection, and preserve embedding model configuration.

## Create a serverless index from a backup

When restoring a serverless index from backup, you can change the index name, tags, and deletion protection setting. All other properties of the restored index will remain identical to the source index, including cloud and region by default, dimension and similarity metric, and associated embedding model when restoring an index with [integrated embedding](/guides/index-data/indexing-overview#integrated-embedding). To restore a backup into a different region than the source index, see [Restore to a different region](#restore-to-a-different-region).

To [create a serverless index from a backup](/reference/api/latest/control-plane/create_index_from_backup), provide the ID of the backup, the name of the new index, and, optionally, changes to the index tags and deletion protection settings:

<CodeGroup>
  ```python Python theme={null}
  from pinecone import Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")

  pc.create_index_from_backup(
      backup_id="a65ff585-d987-4da5-a622-72e19a6ed5f4",
      name="restored-index",
      tags={
          "tag0": "val0", 
          "tag1": "val1"
      },
      deletion_protection="enabled"
  )
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone';

  const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' })

  const response = await pc.createIndexFromBackup({
    backupId: 'a65ff585-d987-4da5-a622-72e19a6ed5f4',
    name: 'restored-index',
    tags: {
      tag0: 'val0',
      tag1: 'val1'
    },
    deletionProtection: 'enabled'
  });

  console.log(response);
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Pinecone;
  import org.openapitools.db_control.client.ApiException;
  import org.openapitools.db_control.client.model.*;

  public class CreateIndexFromBackup {
      public static void main(String[] args) throws ApiException {
          Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build();

          String backupID = "a65ff585-d987-4da5-a622-72e19a6ed5f4";
          String indexName = "restored-index";

          CreateIndexFromBackupResponse backupResponse = pc.createIndexFromBackup(backupID, indexName);
          System.out.println(backupResponse);
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
  	"context"
  	"encoding/json"
  	"fmt"
  	"log"
  	"time"

  	"github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func prettifyStruct(obj interface{}) string {
  	bytes, _ := json.MarshalIndent(obj, "", "  ")
  	return string(bytes)
  }

  func main() {
  	ctx := context.Background()

  	pc, err := pinecone.NewClient(pinecone.NewClientParams{
  		ApiKey: "YOUR_API_KEY",
  	})
  	if err != nil {
  		log.Fatalf("Failed to create Client: %v", err)
  	}

  	indexName := "restored-index"
  	restoredIndexTags := pinecone.IndexTags{"restored_on": time.Now().Format("2006-01-02 15:04")}
  	createIndexFromBackupResp, err := pc.CreateIndexFromBackup(ctx, &pinecone.CreateIndexFromBackupParams{
  		BackupId: "e12269b0-a29b-4af0-9729-c7771dec03e3",
  		Name:     indexName,
  		Tags:     &restoredIndexTags,
  	})

  	fmt.Printf(prettifyStruct(createIndexFromBackupResp))
  }
  ```

  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  BACKUP_ID="a65ff585-d987-4da5-a622-72e19a6ed5f4"

  curl "https://api.pinecone.io/backups/$BACKUP_ID/create-index" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2025-10" \
    -H 'Content-Type: application/json' \
    -d '{
          "name": "restored-index",
          "tags": {
            "tag0": "val0",
            "tag1": "val1"
          },
          "deletion_protection": "enabled"
        }'
  ```
</CodeGroup>

The example returns a response like the following:

<CodeGroup>
  ```python Python theme={null}
  {'deletion_protection': 'enabled',
   'dimension': 1024,
   'embed': {'dimension': 1024,
             'field_map': {'text': 'chunk_text'},
             'metric': 'cosine',
             'model': 'multilingual-e5-large',
             'read_parameters': {'input_type': 'query', 'truncate': 'END'},
             'vector_type': 'dense',
             'write_parameters': {'input_type': 'passage', 'truncate': 'END'}},
   'host': 'example-dense-index-python3-govk0nt.svc.aped-4627-b74a.pinecone.io',
   'metric': 'cosine',
   'name': 'example-dense-index-python3',
   'spec': {'serverless': {'cloud': 'aws', 'region': 'us-east-1'}},
   'status': {'ready': True, 'state': 'Ready'},
   'tags': {'tag0': 'val0', 'tag1': 'val1'},
   'vector_type': 'dense'}
  ```

  ```javascript JavaScript theme={null}
  {
    restoreJobId: 'e9ba8ff8-7948-4cfa-ba43-34227f6d30d4',
    indexId: '025117b3-e683-423c-b2d1-6d30fbe5027f'
  }
  ```

  ```java Java theme={null}
  class CreateIndexFromBackupResponse {
      restoreJobId: e9ba8ff8-7948-4cfa-ba43-34227f6d30d4
      indexId: 025117b3-e683-423c-b2d1-6d30fbe5027f
      additionalProperties: null
  }
  ```

  ```go Go theme={null}
  {
    "index_id": "025117b3-e683-423c-b2d1-6d30fbe5027f",
    "restore_job_id": "e9ba8ff8-7948-4cfa-ba43-34227f6d30d4"
  }
  ```

  ```json curl theme={null}
  {
      "restore_job_id":"e9ba8ff8-7948-4cfa-ba43-34227f6d30d4",
      "index_id":"025117b3-e683-423c-b2d1-6d30fbe5027f"
  }
  ```
</CodeGroup>

<Tip>
  You can create a serverless index from a backup using the [Pinecone console](https://app.pinecone.io/organizations/-/projects).
</Tip>

## Restore to a different region

The [create index from backup](/reference/api/latest/control-plane/create_index_from_backup) endpoint always creates the new index in the same cloud and region as the backup. To restore a backup into a different region, use the `unstable` version of the [create index](/reference/api/latest/control-plane/create_index) endpoint instead. Specify the backup as `source_backup_id` within `spec.serverless` and set the target `region` there.

The following rules apply:

* The target region must be on the same cloud provider as the backup. Restoring to a different cloud provider is not supported.
* The backup must be in the current Pinecone project, and the new index is created in the same project.
* The `dimension`, `metric`, and `vector_type` must match the source index.
* Restoring to a different region is not supported for BYOC indexes.

<Warning>
  Restoring to a different region is in [public preview](/release-notes/feature-availability). It is available through the `unstable` API version and the REST API only.
</Warning>

For example, the following request restores a backup of a dense index hosted in the AWS `us-east-1` region into a new index in the AWS `us-west-2` region:

```bash curl theme={null}
PINECONE_API_KEY="YOUR_API_KEY"

curl "https://api.pinecone.io/indexes" \
  -H "Api-Key: $PINECONE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Pinecone-Api-Version: unstable" \
  -d '{
    "name": "restored-index",
    "vector_type": "dense",
    "dimension": 1536,
    "metric": "cosine",
    "spec": {
      "serverless": {
        "cloud": "aws",
        "region": "us-west-2",
        "source_backup_id": "a65ff585-d987-4da5-a622-72e19a6ed5f4"
      }
    }
  }'
```

Because the backup data is copied between regions, restoring to a different region can take longer than restoring within the same region. If restoring to a different region is not yet available for the backup's region, the request fails with a `412 Precondition Failed` error.

## List restore jobs

You can [list all restore jobs](/reference/api/latest/control-plane/list_restore_jobs) as follows.

<Note>
  Up to 100 restore jobs are returned at a time by default, in sorted order (bitwise “C” collation). If the `limit` parameter is set, up to that number of restore jobs are returned instead. Whenever there are additional restore jobs to return, the response also includes a `pagination_token` that you can use to get the next batch of jobs. When the response does not include a `pagination_token`, there are no more restore jobs to return.
</Note>

<CodeGroup>
  ```python Python theme={null}
  from pinecone import Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")

  restore_jobs = pc.list_restore_jobs()

  print(restore_jobs)
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone';

  const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' })

  const restoreJobs = await pc.listRestoreJobs();

  console.log(restoreJobs);
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Pinecone;
  import org.openapitools.db_control.client.ApiException;
  import org.openapitools.db_control.client.model.*;

  public class CreateIndexFromBackup {
      public static void main(String[] args) throws ApiException {
          Pinecone pc = new Pinecone.Builder("YOUR_API-KEY").build();

          // List all restore jobs with default pagination limit
          RestoreJobList restoreJobList = pc.listRestoreJobs(null, null);

          // List all restore jobs with pagination limit of 5
          RestoreJobList restoreJobListWithLimit = pc.listRestoreJobs(5);

          // List all restore jobs with pagination limit and token
          RestoreJobList restoreJobListPaginated = pc.listRestoreJobs(5, "eyJza2lwX3Bhc3QiOiIxMDEwMy0=");

          System.out.println(restoreJobList);
          System.out.println(restoreJobListWithLimit);
          System.out.println(restoreJobListPaginated);
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
  	"context"
  	"encoding/json"
  	"fmt"
  	"log"

  	"github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func prettifyStruct(obj interface{}) string {
  	bytes, _ := json.MarshalIndent(obj, "", "  ")
  	return string(bytes)
  }

  func main() {
  	ctx := context.Background()

  	pc, err := pinecone.NewClient(pinecone.NewClientParams{
  		ApiKey: "YOUR_API_KEY",
  	})
  	if err != nil {
  		log.Fatalf("Failed to create Client: %v", err)
  	}

  	limit := 2
  	restoreJobs, err := pc.ListRestoreJobs(ctx, &pinecone.ListRestoreJobsParams{
  		Limit: &limit,
  	})
  	if err != nil {
  		log.Fatalf("Failed to list restore jobs: %v", err)
  	}

  	fmt.Printf(prettifyStruct(restoreJobs))
  }
  ```

  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"

  curl "https://api.pinecone.io/restore-jobs" \
  	-H "X-Pinecone-Api-Version: 2025-10" \
  	-H "Api-Key: $PINECONE_API_KEY"
  ```
</CodeGroup>

The example returns a response like the following:

<CodeGroup>
  ```python Python theme={null}
  [{
      "restore_job_id": "06b08366-a0a9-404d-96c2-e791c71743e5",
      "backup_id": "95707edb-e482-49cf-b5a5-312219a51a97",
      "target_index_name": "restored-index",
      "target_index_id": "027aff93-de40-4f48-a573-6dbcd654f961",
      "status": "Completed",
      "created_at": "2025-05-15T13:59:51.439479+00:00",
      "completed_at": "2025-05-15T14:00:09.222998+00:00",
      "percent_complete": 100.0
  }, {
      "restore_job_id": "4902f735-b876-4e53-a05c-bc01d99251cb",
      "backup_id": "8c85e612-ed1c-4f97-9f8c-8194e07bcf71",
      "target_index_name": "restored-index2",
      "target_index_id": "027aff93-de40-4f48-a573-6dbcd654f961",
      "status": "Completed",
      "created_at": "2025-05-15T21:06:19.906074+00:00",
      "completed_at": "2025-05-15T21:06:39.360509+00:00",
      "percent_complete": 100.0
  }]
  ```

  ```javascript JavaScript theme={null}
  {
    data: [
      {
        restoreJobId: '69acc1d0-9105-4fcb-b1db-ebf97b285c5e',
        backupId: '8c85e612-ed1c-4f97-9f8c-8194e07bcf71',
        targetIndexName: 'restored-index2',
        targetIndexId: 'e6c0387f-33db-4227-9e91-32181106e56b',
        status: 'Completed',
        createdAt: 2025-05-14T17:25:59.378Z,
        completedAt: 2025-05-14T17:26:23.997Z,
        percentComplete: 100
      },
      {
        restoreJobId: '9857add2-99d4-4399-870e-aa7f15d8d326',
        backupId: '94a63aeb-efae-4f7a-b059-75d32c27ca57',
        targetIndexName: 'restored-index',
        targetIndexId: '0d8aed24-adf8-4b77-8e10-fd674309dc85',
        status: 'Completed',
        createdAt: 2025-04-25T18:14:05.227Z,
        completedAt: 2025-04-25T18:14:11.074Z,
        percentComplete: 100
      }
    ],
    pagination: undefined
  }
  ```

  ```java Java theme={null}
  class RestoreJobList {
      data: [class RestoreJobModel {
          restoreJobId: cf597d76-4484-4b6c-b07c-2bfcac3388aa
          backupId: 0d75b99f-be61-4a93-905e-77201286c02e
          targetIndexName: restored-index
          targetIndexId: 8a810881-1505-46c0-b906-947c048b15f5
          status: Completed
          createdAt: 2025-05-16T20:09:18.700631Z
          completedAt: 2025-05-16T20:11:30.673296Z
          percentComplete: 100.0
          additionalProperties: null
      }, class RestoreJobModel {
          restoreJobId: 4902f735-b876-4e53-a05c-bc01d99251cb
          backupId: 8c85e612-ed1c-4f97-9f8c-8194e07bcf71
          targetIndexName: restored-index2
          targetIndexId: 710cb6e6-bfb4-4bf5-a425-9754e5bbc832
          status: Completed
          createdAt: 2025-05-15T21:06:19.906074Z
          completedAt: 2025-05-15T21:06:39.360509Z
          percentComplete: 100.0
          additionalProperties: null
      }]
      pagination: class PaginationResponse {
          next: eyJsaW1pdCI6Miwib2Zmc2V0IjoyfQ==
          additionalProperties: null
      }
      additionalProperties: null
  }
  ```

  ```go Go theme={null}
  {
    "data": [
      {
        "backup_id": "8c85e612-ed1c-4f97-9f8c-8194e07bcf71",
        "completed_at": "2025-05-16T20:11:30.673296Z",
        "created_at": "2025-05-16T20:09:18.700631Z",
        "percent_complete": 100,
        "restore_job_id": "e9ba8ff8-7948-4cfa-ba43-34227f6d30d4",
        "status": "Completed",
        "target_index_id": "025117b3-e683-423c-b2d1-6d30fbe5027f",
        "target_index_name": "restored-index"
      },
      {
        "backup_id": "95707edb-e482-49cf-b5a5-312219a51a97",
        "completed_at": "2025-05-15T21:04:34.2463Z",
        "created_at": "2025-05-15T21:04:15.949067Z",
        "percent_complete": 100,
        "restore_job_id": "eee4f8b8-cd3e-45fe-9ed5-93c28e237f24",
        "status": "Completed",
        "target_index_id": "5a0d555f-7ccd-422a-a3a6-78f7b73350c0",
        "target_index_name": "restored-index2"
      }
    ],
    "pagination": {
      "next": "eyJsaW1pdCI6MTAsIm9mZnNldCI6MTB9"
    }
  }
  ```

  ```json curl theme={null}
  {
    "data": [
      {
        "restore_job_id": "9857add2-99d4-4399-870e-aa7f15d8d326",
        "backup_id": "94a63aeb-efae-4f7a-b059-75d32c27ca57",
        "target_index_name": "restored-index",
        "target_index_id": "0d8aed24-adf8-4b77-8e10-fd674309dc85",
        "status": "Completed",
        "created_at": "2025-04-25T18:14:05.227526Z",
        "completed_at": "2025-04-25T18:14:11.074618Z",
        "percent_complete": 100
      },
      {
        "restore_job_id": "69acc1d0-9105-4fcb-b1db-ebf97b285c5e",
        "backup_id": "8c85e612-ed1c-4f97-9f8c-8194e07bcf71",
        "target_index_name": "restored-index2",
        "target_index_id": "e6c0387f-33db-4227-9e91-32181106e56b",
        "status": "Completed",
        "created_at": "2025-05-14T17:25:59.378989Z",
        "completed_at": "2025-05-14T17:26:23.997284Z",
        "percent_complete": 100
      }
    ],
    "pagination": null
  }
  ```
</CodeGroup>

## View restore job details

You can [view the details of a specific restore job](/reference/api/latest/control-plane/describe_restore_job), as in the following example:

<CodeGroup>
  ```python Python theme={null}
  from pinecone import Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")

  restore_job = pc.describe_restore_job(job_id="9857add2-99d4-4399-870e-aa7f15d8d326")

  print(restore_job)
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone';

  const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' })

  const restoreJob = await pc.describeRestoreJob('9857add2-99d4-4399-870e-aa7f15d8d326');

  console.log(restoreJob);
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Pinecone;
  import org.openapitools.db_control.client.ApiException;
  import org.openapitools.db_control.client.model.*;

  public class CreateIndexFromBackup {
      public static void main(String[] args) throws ApiException {
          Pinecone pc = new Pinecone.Builder("YOUR_API-KEY").build();

          RestoreJobModel restoreJob = pc.describeRestoreJob("9857add2-99d4-4399-870e-aa7f15d8d326");

          System.out.println(restoreJob);
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
  	"context"
  	"encoding/json"
  	"fmt"
  	"log"

  	"github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func prettifyStruct(obj interface{}) string {
  	bytes, _ := json.MarshalIndent(obj, "", "  ")
  	return string(bytes)
  }

  func main() {
  	ctx := context.Background()

  	pc, err := pinecone.NewClient(pinecone.NewClientParams{
  		ApiKey: "YOUR_API_KEY",
  	})
  	if err != nil {
  		log.Fatalf("Failed to create Client: %v", err)
  	}

  	restoreJob, err := pc.DescribeRestoreJob(ctx, "e9ba8ff8-7948-4cfa-ba43-34227f6d30d4")
  	if err != nil {
  		log.Fatalf("Failed to describe restore job: %v", err)
  	}

  	fmt.Printf(prettifyStruct(restoreJob))
  }
  ```

  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  JOB_ID="9857add2-99d4-4399-870e-aa7f15d8d326"

  curl "https://api.pinecone.io/restore-jobs/$JOB_ID" \
      -H "X-Pinecone-Api-Version: 2025-10" \
      -H "Api-Key: $PINECONE_API_KEY" \
      -H 'accept: application/json'
  ```
</CodeGroup>

The example returns a response like the following:

<CodeGroup>
  ```python Python theme={null}
  {'backup_id': '94a63aeb-efae-4f7a-b059-75d32c27ca57',
   'completed_at': datetime.datetime(2025, 4, 25, 18, 14, 11, 74618, tzinfo=tzutc()),
   'created_at': datetime.datetime(2025, 4, 25, 18, 14, 5, 227526, tzinfo=tzutc()),
   'percent_complete': 100.0,
   'restore_job_id': '9857add2-99d4-4399-870e-aa7f15d8d326',
   'status': 'Completed',
   'target_index_id': '0d8aed24-adf8-4b77-8e10-fd674309dc85',
   'target_index_name': 'restored-index'}
  ```

  ```javascript JavaScript theme={null}
  {
    restoreJobId: '9857add2-99d4-4399-870e-aa7f15d8d326',
    backupId: '94a63aeb-efae-4f7a-b059-75d32c27ca57',
    targetIndexName: 'restored-index',
    targetIndexId: '0d8aed24-adf8-4b77-8e10-fd674309dc85',
    status: 'Completed',
    createdAt: 2025-04-25T18:14:05.227Z,
    completedAt: 2025-04-25T18:14:11.074Z,
    percentComplete: 100
  }
  ```

  ```java Java theme={null}
  class RestoreJobModel {
      restoreJobId: cf597d76-4484-4b6c-b07c-2bfcac3388aa
      backupId: 0d75b99f-be61-4a93-905e-77201286c02e
      targetIndexName: restored-index
      targetIndexId: 0d8aed24-adf8-4b77-8e10-fd674309dc85
      status: Completed
      createdAt: 2025-05-16T20:09:18.700631Z
      completedAt: 2025-05-16T20:11:30.673296Z
      percentComplete: 100.0
      additionalProperties: null
  }
  ```

  ```go Go theme={null}
  {
    "backup_id": "8c85e612-ed1c-4f97-9f8c-8194e07bcf71",
    "completed_at": "2025-05-16T20:11:30.673296Z",
    "created_at": "2025-05-16T20:09:18.700631Z",
    "percent_complete": 100,
    "restore_job_id": "e9ba8ff8-7948-4cfa-ba43-34227f6d30d4",
    "status": "Completed",
    "target_index_id": "025117b3-e683-423c-b2d1-6d30fbe5027f",
    "target_index_name": "restored-index"
  }
  ```

  ```json curl theme={null}
  {
    "restore_job_id": "9857add2-99d4-4399-870e-aa7f15d8d326",
    "backup_id": "94a63aeb-efae-4f7a-b059-75d32c27ca57",
    "target_index_name": "restored-index",
    "target_index_id": "0d8aed24-adf8-4b77-8e10-fd674309dc85",
    "status": "Completed",
    "created_at": "2025-04-25T18:14:05.227526Z",
    "completed_at": "2025-04-25T18:14:11.074618Z",
    "percent_complete": 100
  }
  ```
</CodeGroup>


# Target an index
Source: https://docs.pinecone.io/guides/manage-data/target-an-index

Target a Pinecone index by host URL (recommended for production) or by name for data operations like upsert, query, and fetch across SDKs.

<Warning>
  **Do not target an index by name in production.**

  When you target an index by name for data operations such as `upsert` and `query`, the SDK gets the unique DNS host for the index using the `describe_index` operation. This is convenient for testing but should be avoided in production because `describe_index` uses a different API than data operations and therefore adds an additional network call and point of failure. Instead, you should get an index host once and cache it for reuse or specify the host directly.
</Warning>

## Target by index host (recommended)

This method is recommended for production:

<Note>
  When using Private Endpoints for private connectivity between your application and Pinecone, you must target the index using the [Private Endpoint URL](/guides/production/configure-private-endpoints#read-and-write-data) for the host.
</Note>

<CodeGroup>
  ```Python Python {5} theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")

  index = pc.Index(host="INDEX_HOST")
  ```

  ```javascript JavaScript {6} theme={null}
  import { Pinecone } from '@pinecone-database/pinecone';

  const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' });

  // For the Node.js SDK, you must specify both the index host and name.
  const index = pc.index("INDEX_NAME", "INDEX_HOST");
  ```

  ```java Java {11} theme={null}
  import io.pinecone.clients.Index;
  import io.pinecone.configs.PineconeConfig;
  import io.pinecone.configs.PineconeConnection;

  public class TargetIndexByHostExample {
      public static void main(String[] args) {
          PineconeConfig config = new PineconeConfig("YOUR_API_KEY");
          config.setHost("INDEX_HOST");
          PineconeConnection connection = new PineconeConnection(config);
          // For the Java SDK, you must specify both the index host and name.
          Index index = new Index(connection, "INDEX_NAME");
      }
  }
  ```

  ```go Go {21} theme={null}
  package main

  import (
      "context"
      "fmt"
      "log"

      "github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

      // This creates a new gRPC index connection, targeting the namespace "example-namespace"
      idxConnectionNs1, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST", Namespace: "example-namespace"})
      if err != nil {
          log.Fatalf("Failed to create IndexConnection for Host %v: %v", idx.Host, err)
      }

      // This reuses the gRPC index connection, targeting a different namespace
  	idxConnectionNs2 := idxConnectionNs1.WithNamespace("example-namespace2")
  }
  ```
</CodeGroup>

### Get an index host

You can get the unique DNS host for an index from the Pinecone console or the Pinecone API.

To get an index host from the Pinecone console:

1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects).
2. Select the project containing the index.
3. Select the index.
4. Copy the URL under **HOST**.

To get an index host from the Pinecone API, use the [`describe_index`](/reference/api/latest/control-plane/describe_index) operation, which returns the index host as the `host` value:

<CodeGroup>
  ```Python Python theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")

  pc.describe_index(name="docs-example")

  # Response:
  # {'deletion_protection': 'disabled',
  #  'dimension': 1536,
  #  'host': 'docs-example-4zo0ijk.svc.us-east1-aws.pinecone.io',
  #  'metric': 'cosine',
  #  'name': 'docs-example',
  #  'spec': {'serverless': {'cloud': 'aws', 'region': 'us-east-1'}},
  #  'status': {'ready': True, 'state': 'Ready'}}
  ```

  ```JavaScript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone';

  const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' });

  await pc.describeIndex('docs-example');

  // Response:
  // {
  //    "name": "docs-example",
  //    "dimension": 1536,
  //    "metric": "cosine",
  //    "host": "docs-example-4zo0ijk.svc.us-east1-aws.pinecone.io",
  //    "deletionProtection": "disabled",
  //    "spec": {
  //       "serverless": {
  //          "cloud": "aws",
  //          "region": "us-east-1"
  //       }
  //    },
  //    "status": {
  //       "ready": true,
  //       "state": "Ready"
  //    }
  // }
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Pinecone;
  import org.openapitools.db_control.client.model.*;

  public class DescribeIndexExample {
      public static void main(String[] args) {
          Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build();
          IndexModel indexModel = pc.describeIndex("docs-example");
          System.out.println(indexModel);
      }
  }

  // Response:
  // class IndexModel {
  //     name: docs-example-java
  //     dimension: 1536
  //     metric: cosine
  //     host: docs-example-4zo0ijk.svc.us-west2-aws.pinecone.io
  //     deletionProtection: enabled
  //     spec: class IndexModelSpec {
  //         pod: null
  //         serverless: class ServerlessSpec {
  //             cloud: aws
  //             region: us-east-1
  //         }
  //     }
  //     status: class IndexModelStatus {
  //         ready: true
  //         state: Ready
  //     }
  // }
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "encoding/json"
      "fmt"
      "log"

      "github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func prettifyStruct(obj interface{}) string {
      bytes, _ := json.MarshalIndent(obj, "", "  ")
      return string(bytes)
  }

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

      idx, err := pc.DescribeIndex(ctx, "docs-example")
      if err != nil {
          log.Fatalf("Failed to describe index \"%v\": %v", idx.Name, err)
      } else {
          fmt.Printf("index: %v\n", prettifyStruct(idx))
      }
  }

  // Response:
  // index: {
  // 	"name": "docs-example",
  // 	"dimension": 1536,
  // 	"host": "docs-example-govk0nt.svc.apw5-4e34-81fa.pinecone.io",
  // 	"metric": "cosine",
  //  "deletion_protection": "disabled",
  // 	"spec": {
  // 	  "serverless": {
  // 		"cloud": "aws",
  // 		"region": "us-east-1"
  // 	  }
  // 	},
  // 	"status": {
  // 	  "ready": true,
  // 	  "state": "Ready"
  // 	}
  // }
  ```

  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"

  curl -i -X GET "https://api.pinecone.io/indexes/docs-example-curl" \
      -H "Api-Key: $PINECONE_API_KEY" \
      -H "X-Pinecone-Api-Version: 2025-10"

  # Response:
  # {
  #    "name": "docs-example",
  #    "metric": "cosine",
  #    "dimension": 1536,
  #    "status": {
  #       "ready": true,
  #       "state": "Ready"
  #    },
  #    "host": "docs-example-4zo0ijk.svc.us-east1-aws.pinecone.io",
  #    "spec": {
  #       "serverless": {
  #          "region": "us-east-1",
  #          "cloud": "aws"
  #       }
  #    }
  # }
  ```
</CodeGroup>

## Target by index name

This method is convenient for testing but is not recommended for production:

<CodeGroup>
  ```Python Python theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")

  index = pc.Index("docs-example")
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone';

  const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' });

  // For the Node.js SDK, you must specify both the index host and name.
  const index = pc.index('docs-example');
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Index;
  import io.pinecone.clients.Pinecone;

  public class GenerateEmbeddings {
      public static void main(String[] args) throws ApiException {
          Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build();
          Index index = pc.getIndexConnection("docs-example");
      }
  }
  ```

  ```go Go theme={null}
  // It is not possible to target an index by name in the Go SDK. 
  // You must target an index by host.
  ```
</CodeGroup>


# Update records
Source: https://docs.pinecone.io/guides/manage-data/update-data

Update Pinecone records by ID to change vector values or metadata, or update metadata across multiple records using a metadata filter expression.

You can [update](/reference/api/latest/data-plane/update) a single record using the record ID or multiple records using a metadata filter.

* **Update by ID**: Update a single record's metadata (add or change fields) or vector values.
* **Update by metadata**: Update metadata (add or change fields) across multiple records using a metadata filter. Vector values cannot be updated.

To update entire records, use the [upsert](/guides/index-data/upsert-data) operation instead.

<Tip>
  Updates consume [write units (WUs)](/guides/manage-cost/understanding-cost#write-units). See [Understanding cost](/guides/manage-cost/understanding-cost#update) for how update cost is calculated.
</Tip>

## Update by ID

To update the vector and/or metadata of a single record, use the [`update`](/reference/api/latest/data-plane/update) operation with the following parameters:

* `namespace`: The [namespace](/guides/index-data/indexing-overview#namespaces) containing the record to update. To use the default namespace, set the namespace to `"__default__"`.
* `id`: The ID of the record to update.
* One or both of the following:
  * Updated values for the vector. Specify one of the following:
    * `values`: For dense vectors. Must have the same length as the existing vector.
    * `sparse_values`: For sparse vectors.
  * `setMetadata`: The metadata to add or change. When updating metadata, only the specified metadata fields are modified, and if a specified metadata field does not exist, it is added.

<Warning>
  If a non-existent record ID is specified, no records are affected and a `200 OK` status is returned.
</Warning>

In this example, assume you are updating the dense vector values and one metadata value of the following record in the `example-namespace` namespace:

```
(
    namespace="example-namespace",
    id="id-3", 
    values=[4.0, 2.0], 
    setMetadata={"type": "doc", "genre": "drama"}
)
```

<CodeGroup>
  ```Python Python theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")

  # To get the unique host for an index, 
  # see https://docs.pinecone.io/guides/manage-data/target-an-index
  index = pc.Index(host="INDEX_HOST")

  index.update(
  	namespace="example-namespace",
  	id="id-3", 
  	values=[5.0, 3.0], 
  	set_metadata={"genre": "comedy"}
  )
  ```

  ```JavaScript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone'

  const pc = new Pinecone({ apiKey: "YOUR_API_KEY" })

  // To get the unique host for an index, 
  // see https://docs.pinecone.io/guides/manage-data/target-an-index
  const index = pc.index("INDEX_NAME", "INDEX_HOST")

  await index.namespace('example-namespace').update({
    id: 'id-3',
    values: [5.0, 3.0],
    metadata: {
      genre: "comedy",
    },
  });
  ```

  ```java Java theme={null}
  import com.google.protobuf.Struct;
  import com.google.protobuf.Value;
  import io.pinecone.clients.Index;
  import io.pinecone.configs.PineconeConfig;
  import io.pinecone.configs.PineconeConnection;
  import io.pinecone.proto.UpdateResponse;

  import java.util.Arrays;
  import java.util.List;

  public class UpdateExample {
      public static void main(String[] args) {
          PineconeConfig config = new PineconeConfig("YOUR_API_KEY");
          // To get the unique host for an index, 
          // see https://docs.pinecone.io/guides/manage-data/target-an-index
          config.setHost("INDEX_HOST");
          PineconeConnection connection = new PineconeConnection(config);
          Index index = new Index(connection, "INDEX_NAME");
          List<Float> values = Arrays.asList(5.0f, 3.0f);
  		Struct metaData = Struct.newBuilder()
  			.putFields("genre",
  					Value.newBuilder().setStringValue("comedy").build())
  			.build();
          UpdateResponse updateResponse = index.update("id-3", values, metaData, "example-namespace", null, null);
          System.out.println(updateResponse);
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "log"

      "github.com/pinecone-io/go-pinecone/v4/pinecone"
      "google.golang.org/protobuf/types/known/structpb"
  )

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

      // To get the unique host for an index, 
      // see https://docs.pinecone.io/guides/manage-data/target-an-index
      idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST", Namespace: "example-namespace"})
      if err != nil {
          log.Fatalf("Failed to create IndexConnection for Host: %v", err)
    	}

      id := "id-3"

      metadataMap := map[string]interface{}{
          "genre": "comedy",
      }

      metadataFilter, err := structpb.NewStruct(metadataMap)
      if err != nil {
          log.Fatalf("Failed to create metadata map: %v", err)
      }

      err = idxConnection.UpdateVector(ctx, &pinecone.UpdateVectorRequest{
          Id:       id,
          Values: []float32{5.0, 3.0},
          Metadata: metadataFilter,
      })
      if err != nil {
          log.Fatalf("Failed to update vector with ID %v: %v", id, err)
      }
  }
  ```

  ```bash curl theme={null}
  # To get the unique host for an index,
  # see https://docs.pinecone.io/guides/manage-data/target-an-index
  PINECONE_API_KEY="YOUR_API_KEY"
  INDEX_HOST="INDEX_HOST"

  # Update both values and metadata
  curl "https://$INDEX_HOST/vectors/update" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H 'Content-Type: application/json' \
    -H "X-Pinecone-Api-Version: 2025-10" \
    -d '{
          "id": "id-3",
          "values": [5.0, 3.0],
          "setMetadata": {"genre": "comedy"},
          "namespace": "example-namespace"
        }'
  ```
</CodeGroup>

After the update, the dense vector values and the `genre` metadata value are changed, but the `type` metadata value is unchanged:

```
(
    id="id-3", 
    values=[5.0, 3.0], 
    metadata={"type": "doc", "genre": "comedy"}
)
```

## Update by metadata

To add or change metadata across multiple records in a namespace, use the `update` operation with the following parameters:

* `namespace`: The [namespace](/guides/index-data/indexing-overview#namespaces) containing the records to update. To use the default namespace, set this to `"__default__"`.
* `filter`: A [metadata filter expression](/guides/index-data/indexing-overview#metadata-filter-expressions) to match the records to update.
* `setMetadata`: The metadata to add or change. When updating metadata, only the specified metadata fields are modified. If a specified metadata field does not exist, it is added.
* `dry_run`: Optional. If `true`, the number of records that match the filter expression is returned, but the records are not updated.

  <Note>
    Each request updates a maximum of 100,000 records. Use `"dry_run": true` to check if you need to run the request multiple times. See the example below for details.
  </Note>

For example, let's say you have records that represent chunks of a single document with metadata that keeps track of chunk and document details, and you want to store the author's name with each chunk of the document:

```json theme={null}
{
    "id": "document1#chunk1", 
    "values": [0.0236663818359375, -0.032989501953125, ..., -0.01041412353515625, 0.0086669921875], 
    "metadata": {
        "document_id": "document1",
        "document_title": "Introduction to Vector Databases",
        "chunk_number": 1,
        "chunk_text": "First chunk of the document content...",
        "document_url": "https://example.com/docs/document1"
    }
},
{
    "id": "document1#chunk2", 
    "values": [-0.0412445068359375, 0.028839111328125, ..., 0.01953125, -0.0174560546875],
    "metadata": {
        "document_id": "document1",
        "document_title": "Introduction to Vector Databases", 
        "chunk_number": 2,
        "chunk_text": "Second chunk of the document content...",
        "document_url": "https://example.com/docs/document1"
    }
},
...
```

The following code updates all matching records with the new `author` metadata field:

<CodeGroup>
  ```Python Python theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")

  # To get the unique host for an index, 
  # see https://docs.pinecone.io/guides/manage-data/target-an-index
  index = pc.Index(host="INDEX_HOST")

  # Use dry_run to check how many records match the filter
  dry_run_response = index.update(
      namespace="example-namespace",
      filter={"document_title": {"$eq": "Introduction to Vector Databases"}},
      set_metadata={"author": "Del Klein"},
      dry_run=True
  )
  print(dry_run_response.matched_records)

  # Perform the update
  response = index.update(
      namespace="example-namespace",
      filter={"document_title": {"$eq": "Introduction to Vector Databases"}},
      set_metadata={"author": "Del Klein"}
  )
  ```

  ```JavaScript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone'

  const pc = new Pinecone({ apiKey: "YOUR_API_KEY" })

  // To get the unique host for an index, 
  // see https://docs.pinecone.io/guides/manage-data/target-an-index
  const index = pc.index("INDEX_NAME", "INDEX_HOST")

  await index.namespace('example-namespace').update({
    filter: { document_title: { $eq: 'Introduction to Vector Databases' } },
    metadata: { author: 'Del Klein' },
  });
  ```

  ```java Java theme={null}
  import com.google.protobuf.Struct;
  import com.google.protobuf.Value;
  import io.pinecone.clients.Index;
  import io.pinecone.configs.PineconeConfig;
  import io.pinecone.configs.PineconeConnection;
  import io.pinecone.proto.UpdateResponse;

  public class UpdateByMetadataExample {
      public static void main(String[] args) {
          PineconeConfig config = new PineconeConfig("YOUR_API_KEY");
          // To get the unique host for an index, 
          // see https://docs.pinecone.io/guides/manage-data/target-an-index
          config.setHost("INDEX_HOST");
          PineconeConnection connection = new PineconeConnection(config);
          Index index = new Index(connection, "INDEX_NAME");

          Struct filter = Struct.newBuilder()
              .putFields("document_title", Value.newBuilder()
                  .setStructValue(Struct.newBuilder()
                      .putFields("$eq", Value.newBuilder()
                          .setStringValue("Introduction to Vector Databases")
                          .build())
                      .build())
                  .build())
              .build();

          Struct metadata = Struct.newBuilder()
              .putFields("author", Value.newBuilder()
                  .setStringValue("Del Klein")
                  .build())
              .build();

          // Dry run to check how many records match
          UpdateResponse dryRunResponse = index.updateByMetadata(
              filter, metadata, "example-namespace", true);
          System.out.println("Matched records: " + dryRunResponse.getMatchedRecords());

          // Perform the update
          UpdateResponse response = index.updateByMetadata(
              filter, metadata, "example-namespace");
          System.out.println(response);
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "fmt"
      "log"

      "github.com/pinecone-io/go-pinecone/v4/pinecone"
      "google.golang.org/protobuf/types/known/structpb"
  )

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

      // To get the unique host for an index, 
      // see https://docs.pinecone.io/guides/manage-data/target-an-index
      idxConnection, err := pc.Index(pinecone.NewIndexConnParams{
          Host:      "INDEX_HOST",
          Namespace: "example-namespace",
      })
      if err != nil {
          log.Fatalf("Failed to create IndexConnection for Host: %v", err)
      }

      filter, err := structpb.NewStruct(map[string]interface{}{
          "document_title": map[string]interface{}{
              "$eq": "Introduction to Vector Databases",
          },
      })
      if err != nil {
          log.Fatalf("Failed to create filter: %v", err)
      }

      metadata, err := structpb.NewStruct(map[string]interface{}{
          "author": "Del Klein",
      })
      if err != nil {
          log.Fatalf("Failed to create metadata: %v", err)
      }

      // Dry run to check how many records match
      dryRun := true
      dryRunRes, err := idxConnection.UpdateVectorsByMetadata(ctx, &pinecone.UpdateVectorsByMetadataRequest{
          Filter:   filter,
          Metadata: metadata,
          DryRun:   &dryRun,
      })
      if err != nil {
          log.Fatalf("Failed to dry run update: %v", err)
      }
      fmt.Printf("Matched records: %d\n", dryRunRes.MatchedRecords)

      // Perform the update
      res, err := idxConnection.UpdateVectorsByMetadata(ctx, &pinecone.UpdateVectorsByMetadataRequest{
          Filter:   filter,
          Metadata: metadata,
      })
      if err != nil {
          log.Fatalf("Failed to update vectors by metadata: %v", err)
      }
      fmt.Printf("Updated records: %d\n", res.MatchedRecords)
  }
  ```

  ```bash curl theme={null}
  # To get the unique host for an index,
  # see https://docs.pinecone.io/guides/manage-data/target-an-index
  PINECONE_API_KEY="YOUR_API_KEY"
  INDEX_HOST="INDEX_HOST"

  curl "https://$INDEX_HOST/vectors/update" \
      -H "Api-Key: $PINECONE_API_KEY" \
      -H 'Content-Type: application/json' \
      -H "X-Pinecone-Api-Version: 2025-10" \
      -d '{
              "namespace": "example-namespace",
              "filter": {
                  "document_title": {"$eq": "Introduction to Vector Databases"}
              },
              "setMetadata": {
                  "author": "Del Klein"
              } 
          }'
  ```
</CodeGroup>

### Handling large updates

<Tip>
  If you need to update most of the records in a large namespace, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) for help creating an export to enable a faster and more cost-effective approach.
</Tip>

Each request updates a maximum of 100,000 records. For larger datasets, use `dry_run` to check the count and repeat the request as needed:

1. To check how many records match the filter expression, send a request with `dry_run` set to `true`:

   ```bash curl {11} theme={null}
   # To get the unique host for an index,
   # see https://docs.pinecone.io/guides/manage-data/target-an-index
   PINECONE_API_KEY="YOUR_API_KEY"
   INDEX_HOST="INDEX_HOST"

   curl "https://$INDEX_HOST/vectors/update" \
       -H "Api-Key: $PINECONE_API_KEY" \
       -H 'Content-Type: application/json' \
       -H "X-Pinecone-Api-Version: 2025-10" \
       -d '{
               "dry_run": true,
               "namespace": "example-namespace",
               "filter": {
                   "document_title": {"$eq": "Introduction to Vector Databases"}
               },
               "setMetadata": {
                   "author": "Del Klein"
               } 
           }'
   ```

   The response contains the number of records that match the filter expression:

   ```json theme={null}
   {
       "matchedVectors": 150000
   }
   ```

   Since this number exceeds the 100,000 record limit, you'll need to run the update request multiple times.

2. Initiate the first update by sending the request without the `dry_run` parameter:

   ```bash curl theme={null}
   curl "https://$INDEX_HOST/vectors/update" \
       -H "Api-Key: $PINECONE_API_KEY" \
       -H 'Content-Type: application/json' \
       -H "X-Pinecone-Api-Version: 2025-10" \
       -d '{
               "namespace": "example-namespace",
               "filter": {
                   "document_title": {"$eq": "Introduction to Vector Databases"}
               },
               "setMetadata": {
                   "author": "Del Klein"
               } 
           }'
   ```

   Again, the response contains the total number of records that match the filter expression, but only 100,000 will be updated:

   ```json theme={null}
   {
       "matchedVectors": 150000
   }
   ```

3. Pinecone is eventually consistent, so there can be a slight delay before your update request is processed. Repeat the `dry_run` request until the number of matching records shows that the first 100,000 records have been updated:

   ```bash curl {11} theme={null}
   # To get the unique host for an index,
   # see https://docs.pinecone.io/guides/manage-data/target-an-index
   PINECONE_API_KEY="YOUR_API_KEY"
   INDEX_HOST="INDEX_HOST"

   curl "https://$INDEX_HOST/vectors/update" \
       -H "Api-Key: $PINECONE_API_KEY" \
       -H 'Content-Type: application/json' \
       -H "X-Pinecone-Api-Version: 2025-10" \
       -d '{
               "dry_run": true,
               "namespace": "example-namespace",
               "filter": {
                   "document_title": {"$eq": "Introduction to Vector Databases"}
               },
               "setMetadata": {
                   "author": "Del Klein"
               } 
           }'
   ```

   ```json theme={null}
   {
       "matchedVectors": 50000
   }
   ```

4. Once the first 100,000 records have been updated, update the remaining records:

   ```bash curl theme={null}
   curl "https://$INDEX_HOST/vectors/update" \
       -H "Api-Key: $PINECONE_API_KEY" \
       -H 'Content-Type: application/json' \
       -H "X-Pinecone-Api-Version: 2025-10" \
       -d '{
               "namespace": "example-namespace",
               "filter": {
                   "document_title": {"$eq": "Introduction to Vector Databases"}
               },
               "setMetadata": {
                   "author": "Del Klein"
               } 
           }'
   ```

5. Repeat the `dry_run` request until the number of matching records shows that the remaining records have been updated:

   ```bash curl {11} theme={null}
   # To get the unique host for an index,
   # see https://docs.pinecone.io/guides/manage-data/target-an-index
   PINECONE_API_KEY="YOUR_API_KEY"
   INDEX_HOST="INDEX_HOST"

   curl "https://$INDEX_HOST/vectors/update" \
       -H "Api-Key: $PINECONE_API_KEY" \
       -H 'Content-Type: application/json' \
       -H "X-Pinecone-Api-Version: 2025-10" \
       -d '{
               "dry_run": true,
               "namespace": "example-namespace",
               "filter": {
                   "document_title": {"$eq": "Introduction to Vector Databases"}
               },
               "setMetadata": {
                   "author": "Del Klein"
               } 
           }'
   ```

   ```json theme={null}
   {
       "matchedVectors": 0
   }
   ```

   Once the request has completed, all matching records include the author name as metadata:

   ```json {10,22} theme={null}
   {
       "id": "document1#chunk1", 
       "values": [0.0236663818359375, -0.032989501953125, ..., -0.01041412353515625, 0.0086669921875], 
       "metadata": {
           "document_id": "document1",
           "document_title": "Introduction to Vector Databases",
           "chunk_number": 1,
           "chunk_text": "First chunk of the document content...",
           "document_url": "https://example.com/docs/document1",
           "author": "Del Klein"
       }
   },
   {
       "id": "document1#chunk2", 
       "values": [-0.0412445068359375, 0.028839111328125, ..., 0.01953125, -0.0174560546875],
       "metadata": {
           "document_id": "document1",
           "document_title": "Introduction to Vector Databases", 
           "chunk_number": 2,
           "chunk_text": "Second chunk of the document content...",
           "document_url": "https://example.com/docs/document1",
           "author": "Del Klein"
       }
   },
   ...
   ```

### Limitations

* Each request updates a maximum of 100,000 records. Use `"dry_run": true` to check if you need to run the request multiple times. See the example above for details.
* You can add or change metadata across multiple records, but you cannot remove metadata fields.

## Remove a metadata field

To remove a metadata field from a record, use the [upsert](/guides/index-data/upsert-data) operation to replace the record's metadata, providing the record's existing ID and vector values along with only the metadata you want to keep. Because upsert replaces a record's metadata in full, any fields you omit are cleared.

## Data freshness

Pinecone is eventually consistent, so there can be a slight delay before updates are visible to queries. You can [use log sequence numbers](/guides/index-data/check-data-freshness#check-the-log-sequence-number) to check whether an update request has completed.

## See also

* [Update an entire document](/guides/index-data/data-modeling#update-an-entire-document)


# Integrate with Amazon S3
Source: https://docs.pinecone.io/guides/operations/integrations/integrate-with-amazon-s3

Connect Pinecone to an Amazon S3 bucket using an IAM role to import data and export audit logs.

<Note>
  This feature is in [public preview](/release-notes/feature-availability) and available only on [Standard and Enterprise plans](https://www.pinecone.io/pricing/).
</Note>

This page shows you how to integrate Pinecone with an Amazon S3 bucket. Once your integration is set up, you can use it to [import data](/guides/index-data/import-data) from your Amazon S3 bucket into a Pinecone index hosted on AWS, or to [export audit logs](/guides/production/configure-audit-logs) to your Amazon S3 bucket.

## Before you begin

Ensure you have the following:

* A [Pinecone account](https://app.pinecone.io/).
* An [Amazon S3 bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/creating-buckets.html).

## 1. Create an IAM policy

In the [AWS IAM console](https://console.aws.amazon.com/iam/home):

1. In the navigation pane, click **Policies**.
2. Click **Create policy**.
3. In **Select a service** section, select **S3**.
4. Select the following actions to allow:
   * `ListBucket`: Permission to list some or all of the objects in an S3 bucket. Required for [importing data](/guides/index-data/import-data) and [exporting audit logs](/guides/production/configure-audit-logs).
   * `GetObject`: Permission to retrieve objects from an S3 bucket. Required for [importing data](/guides/index-data/import-data).
   * `PutObject`: Permission to add an object to an S3 bucket. Required for [exporting audit logs](/guides/production/configure-audit-logs).
5. In the **Resources** section, select **Specific**.
6. For the **bucket**, specify the ARN of the bucket you created. For example: `arn:aws:s3:::example-bucket-name`
7. For the **object**, specify an object ARN as the target resource. For example: `arn:aws:s3:::example-bucket-name/*`
8. Click **Next**.
9. Specify the name of your policy. For example:  "Pinecone-S3-Access".
10. Click **Create policy**.

### Targeting a subdirectory (optional)

To write [audit logs](/guides/production/configure-audit-logs) to a specific subdirectory within your S3 bucket (e.g., `my-bucket/pinecone-logs/`), you need to configure your IAM policy differently for `ListBucket` vs. object-level actions:

1. For `ListBucket`, use a **Condition** block with `StringLike` to specify the prefix. Include both the directory path with and without the trailing wildcard:

   ```json theme={null}
   {
       "Sid": "ListBucketWithPrefix",
       "Effect": "Allow",
       "Action": "s3:ListBucket",
       "Resource": "arn:aws:s3:::example-bucket-name",
       "Condition": {
           "StringLike": {
               "s3:prefix": [
                   "pinecone-logs/",
                   "pinecone-logs/*"
               ]
           }
       }
   }
   ```

2. For `PutObject` and `GetObject`, use the **Resource** specifier with the subdirectory path:

   ```json theme={null}
   {
       "Sid": "ObjectActionsInSubdirectory",
       "Effect": "Allow",
       "Action": [
           "s3:PutObject",
           "s3:GetObject"
       ],
       "Resource": "arn:aws:s3:::example-bucket-name/pinecone-logs/*"
   }
   ```

**Complete example policy for subdirectory access:**

```json theme={null}
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "ListBucketWithPrefix",
            "Effect": "Allow",
            "Action": "s3:ListBucket",
            "Resource": "arn:aws:s3:::example-bucket-name",
            "Condition": {
                "StringLike": {
                    "s3:prefix": [
                        "pinecone-logs/",
                        "pinecone-logs/*"
                    ]
                }
            }
        },
        {
            "Sid": "ObjectActionsInSubdirectory",
            "Effect": "Allow",
            "Action": [
                "s3:PutObject",
                "s3:GetObject"
            ],
            "Resource": "arn:aws:s3:::example-bucket-name/pinecone-logs/*"
        }
    ]
}
```

<Note>
  The key difference is that `ListBucket` operates on the bucket resource and uses conditions to filter by prefix, while object-level actions (`PutObject`, `GetObject`) operate directly on object resources specified in the ARN.
</Note>

## 2. Set up access using an IAM role

In the [AWS IAM console](https://console.aws.amazon.com/iam/home):

1. In the navigation pane, click **Roles**.

2. Click **Create role**.

3. In the **Trusted entity type** section, select **AWS account**.

4. Select **Another AWS account**.

5. Enter the Pinecone AWS VPC account ID: `713131977538`

6. Click **Next**.

7. Select the [policy you created](#1-create-an-iam-policy).

8. Click **Next**.

9. Specify the role name. For example: "Pinecone".

10. Click **Create role**.

11. Click the role you created.

12. On the **Summary** page for the role, find the **ARN**.

    For example: `arn:aws:iam::123456789012:role/PineconeAccess`

13. Copy the **ARN**.

    You will need to enter the ARN into Pinecone later.

## 3. Add a storage integration

<Note>
  This step is required for [importing data](/guides/index-data/import-data). It is not required for [storing audit logs](/guides/production/configure-audit-logs).
</Note>

In the [Pinecone console](https://app.pinecone.io/organizations/-/projects), add an integration with Amazon S3..

1. Select your project.
2. Go to [**Manage > Storage integrations**](https://app.pinecone.io/organizations/-/projects/-/storage).
3. Click **Add integration**.
4. Enter a unique integration name.
5. Select **Amazon S3**.
6. Enter the **ARN** of the [IAM role you created](/guides/operations/integrations/integrate-with-amazon-s3#2-set-up-access-using-an-iam-role).
7. Click **Add integration**.

## Next steps

* [Import data](/guides/index-data/import-data) from your Amazon S3 bucket into a Pinecone index.
* [Configure audit logs](/guides/production/configure-audit-logs) to export logs to your Amazon S3 bucket.


# Integrate with Azure Blob Storage
Source: https://docs.pinecone.io/guides/operations/integrations/integrate-with-azure-blob-storage

Connect Pinecone to Azure Blob Storage using a service principal to import data into your indexes.

<Note>
  This feature is in [public preview](/release-notes/feature-availability) and available only on [Standard and Enterprise plans](https://www.pinecone.io/pricing/).
</Note>

This page describes how to integrate Pinecone with Azure Blob Storage. After setting up an integration, you can [import data](/guides/index-data/import-data) from an Azure Blob Storage container into a Pinecone index hosted on AWS, GCP, or Azure.

## Before you begin

Ensure you have the following:

* A [Pinecone account](https://app.pinecone.io/)
* An [Azure Blob Storage container](https://learn.microsoft.com/azure/storage/blobs/storage-blobs-introduction)

## 1. Create an app registration and service principal

Pinecone uses a service principal to access your Azure Blob Storage container.

1. [Create an app registration](https://learn.microsoft.com/entra/identity-platform/quickstart-register-app) for your Pinecone integration. This automatically creates a service principal.

   When creating your app registration:

   * Do not specify a **Redirect URI**.
   * Copy the **Application (client) ID** and the **Directory (tenant) ID**. You'll use these values when adding a storage integration in Pinecone.

2. [Create a client secret](https://learn.microsoft.com/entra/identity-platform/how-to-add-credentials?tabs=client-secret) for the service principal.

   Copy the secret's **Value** (not its **ID**). You'll use this when creating a storage integration in Pinecone.

## 2. Grant access to the storage account

[Assign the service principal to your storage account](https://learn.microsoft.com/azure/storage/common/storage-auth-aad-rbac-portal#assign-azure-rbac-roles-using-the-azure-portal):

1. In the Azure portal, navigate to the subscription associated with your storage account.
2. Select **Access control (IAM)**.
3. Click **Add** > **Add role assignment**.
4. Select **Storage Blob Data Reader** or another role that has permission to list and read blobs in a container.
5. Click **Next**.
6. Select **User, group, or service principal** and click **Select members**.
7. Select the app you created in the previous step.
8. Click **Review + assign** (you may need to click this twice).

## 3. In Pinecone, add a storage integration

In the [Pinecone console](https://app.pinecone.io/organizations/-/projects), add an integration with Azure Blob Storage:

1. Select your project.
2. Go to [**Manage > Storage integrations**](https://app.pinecone.io/organizations/-/projects/-/storage).
3. Click **Add integration**.
4. Enter a unique integration name.
5. Select **Azure Blob Storage**.
6. For **Tenant ID**, **Client ID**, and **Client secret**, enter the values you copied from Azure.
7. Click **Add integration**.

## Next steps

[Import data](/guides/index-data/import-data) from your Azure Blob Storage container into your Pinecone index.


# Integrate with Google Cloud Storage
Source: https://docs.pinecone.io/guides/operations/integrations/integrate-with-google-cloud-storage

Connect Pinecone to a Google Cloud Storage bucket with a service account key to import data into your indexes.

<Note>
  This feature is in [public preview](/release-notes/feature-availability) and available only on [Standard and Enterprise plans](https://www.pinecone.io/pricing/).
</Note>

This page shows you how to integrate Pinecone with a Google Cloud Storage (GCS) bucket. Once your integration is set up, you can use it to [import data](/guides/index-data/import-data) from your bucket into a Pinecone index hosted on AWS, GCP, or Azure.

## Before you begin

Ensure you have the following:

* A [Pinecone account](https://app.pinecone.io/)
* A [Google Cloud Storage bucket](https://cloud.google.com/storage/docs/creating-buckets)

## 1. Create a service account and key

Pinecone will use a service account to access your GCS bucket.

1. [Create a service account](https://cloud.google.com/iam/docs/service-accounts-create) for your Pinecone integration.
2. [Create a service account key](https://cloud.google.com/iam/docs/keys-create-delete#creating). Select **JSON** as the key type.

   The key will be downloaded to your computer. You'll use this key when adding a storage integration in Pinecone.

## 2. Grant access to the bucket

[Add your service account as a principal to the bucket](https://cloud.google.com/storage/docs/access-control/using-iam-permissions#bucket-add).

* For the principal, use your service account email address.
* For the role, select **Storage Object Viewer** or another role that has permission to list and read objects in a bucket.

## 3. Add a storage integration

In the [Pinecone console](https://app.pinecone.io/organizations/-/projects), add an integration with Google Cloud Storage:

1. Select your project.
2. Go to [**Manage > Storage integrations**](https://app.pinecone.io/organizations/-/projects/-/storage).
3. Click **Add integration**.
4. Enter a unique integration name.
5. Select **Google Cloud Storage**.
6. Open the JSON key file for your service account.
7. Copy the contents of the key file and paste them into the **Index account key JSON** field.
8. Click **Add integration**.

## Next steps

[Import data](/guides/index-data/import-data) from your GCS bucket into your Pinecone index.


# Manage storage integrations
Source: https://docs.pinecone.io/guides/operations/integrations/manage-storage-integrations

Update or delete existing Amazon S3, Google Cloud Storage, and Azure Blob storage integrations for your Pinecone project in the console.

<Note>
  This feature is available on [Standard and Enterprise plans](https://www.pinecone.io/pricing/).
</Note>

This page shows you how to manage storage integrations for your Pinecone project.

To set up cloud storage for integration with Pinecone, see the following guides:

* [Integrate with Amazon S3](/guides/operations/integrations/integrate-with-amazon-s3)
* [Integrate with Google Cloud Storage](/guides/operations/integrations/integrate-with-google-cloud-storage)
* [Integrate with Azure Blob Storage](/guides/operations/integrations/integrate-with-azure-blob-storage)

## Update an integration

To update information for a storage integration through the [Pinecone console](https://app.pinecone.io/organizations/-/projects), take the following steps:

1. Select your project.
2. Go to [**Manage > Storage integrations**](https://app.pinecone.io/organizations/-/projects/-/storage).
3. For the integration you want to update, click the *...* (Actions) icon.
4. Click **Manage**.
5. Update the integration details as needed.
6. Click **Add integration**.

## Delete an integration

To delete a storage integration through the [Pinecone console](https://app.pinecone.io/organizations/-/projects), take the following steps:

1. Select your project.
2. Go to [**Manage > Storage integrations**](https://app.pinecone.io/organizations/-/projects/-/storage).
3. For the integration you want to update, click the *...* (Actions) icon.
4. Click **Delete**.
5. Enter the integration name.
6. Click **Confirm deletion**.


# Local development with Pinecone Local
Source: https://docs.pinecone.io/guides/operations/local-development

Run Pinecone Local, an in-memory Docker emulator, to develop and test apps offline without an account or usage fees.

Pinecone Local is an in-memory Pinecone emulator available as a Docker image.

This page shows you how to use Pinecone Local to develop your applications locally without connecting to your Pinecone account or incurring usage or storage fees.

<Warning>
  Pinecone Local is not suitable for production. See [Limitations](#limitations) for details.
</Warning>

## Limitations

Pinecone Local has the following limitations:

* Pinecone Local uses the `2025-01` API version, which is not the latest stable version.
* Pinecone Local is available in Docker only.
* Pinecone Local is an in-memory emulator and is not suitable for production. Records loaded into Pinecone Local do not persist after it is stopped.
* Pinecone Local does not authenticate client requests. API keys are ignored.
* Max number of records per index: 100,000.

Pinecone Local does not currently support the following features:

* [Import from object storage](/guides/index-data/import-data)
* [Backup/restore of serverless indexes](/guides/manage-data/backups-overview)
* [Collections for pod-based indexes](/guides/indexes/pods/understanding-collections)
* [Namespace management](/guides/manage-data/manage-namespaces)
* [Pinecone Inference](/reference/api/introduction#inference)
* [Pinecone Assistant](/guides/assistant/overview)

## 1. Start Pinecone Local

You can configure Pinecone Local as an index emulator or database emulator:

* **Index emulator** - This approach uses the `pinecone-index` Docker image to create and configure indexes on startup. This is recommended when you want to quickly experiment with reading and writing data without needing to manage the index lifecycle.

  <Note>
    With index emulation, you can only read and write data to the indexes created at startup. You cannot create new indexes, list indexes, or run other operations that do not involve reading and writing data.
  </Note>

* **Database emulator** - This approach uses the `pinecone-local` Docker image to emulate Pinecone Database more broadly. This is recommended when you want to test your production app or manually create and manage indexes.

### Index emulator

<Tabs>
  <Tab title="Docker Compose">
    Make sure [Docker](https://docs.docker.com/get-docker/) is installed and running on your local machine.

    Create a `docker-compose.yaml` file that defines a service for each index that Pinecone Local should create on startup. In this file, include the `pinecone-index` Docker image, a localhost port for the index to use, and other details:

    ```yaml theme={null}
    services:
      dense-index:
        image: ghcr.io/pinecone-io/pinecone-index:latest
        container_name: dense-index
        environment:
          PORT: 5081
          INDEX_TYPE: serverless
          VECTOR_TYPE: dense
          DIMENSION: 2 
          METRIC: cosine
        ports:
          - "5081:5081"
        platform: linux/amd64
      sparse-index:
        image: ghcr.io/pinecone-io/pinecone-index:latest
        container_name: sparse-index
        environment:
          PORT: 5082
          INDEX_TYPE: serverless
          VECTOR_TYPE: sparse
          DIMENSION: 0
          METRIC: dotproduct
        ports:
          - "5082:5082"
        platform: linux/amd64
    ```

    For each index, update the environment variables as needed:

    * `PORT`: Specify the port number for the index to listen on.
    * `INDEX_TYPE`: Specify the type of Pinecone index to create. Accepted values: `serverless` or `pod`.
    * `VECTOR_TYPE`: Specify the [type of vectors](/guides/index-data/indexing-overview#indexes) you will store in the index. Accepted values: `dense` or `sparse`.

      <Note>Sparse is supported only with serverless indexes.</Note>
    * `DIMENSION`: Specify the dimension of vectors you will store in the index.

      <Note>For indexes that store only sparse vectors, this must be set to `0`.</Note>
    * `METRIC`: Specify the [distance metric](/guides/index-data/indexing-overview#distance-metrics) for calculating the similarity between vectors in the index. Accepted values when storing dense vectors: `cosine`, `euclidean`, or `dotproduct`. Accepted value when storing only sparse vectors: `dotproduct`.

    To start Pinecone Local, run the following command:

    ```shell theme={null}
    docker compose up -d
    ```

    You'll see a message with details about each index.
  </Tab>

  <Tab title="Docker CLI">
    Make sure [Docker](https://docs.docker.com/get-docker/) is installed and running on your local machine.

    Download the latest `pinecone-index` Docker image:

    ```shell theme={null}
    docker pull ghcr.io/pinecone-io/pinecone-index:latest
    ```

    Start Pinecone Local with one or more indexes:

    ```shell theme={null}
    docker run -d \
    --name dense-index \
    -e PORT=5081 \
    -e INDEX_TYPE=serverless \
    -e VECTOR_TYPE=dense \
    -e DIMENSION=2 \
    -e METRIC=cosine \
    -p 5081:5081 \
    --platform linux/amd64 \
    ghcr.io/pinecone-io/pinecone-index:latest
    ```

    ```shell theme={null}
    docker run -d \
    --name sparse-index \
    -e PORT=5082 \
    -e INDEX_TYPE=serverless \
    -e VECTOR_TYPE=sparse \
    -e DIMENSION=0 \
    -e METRIC=dotproduct \
    -p 5082:5082 \
    --platform linux/amd64 \
    ghcr.io/pinecone-io/pinecone-index:latest
    ```

    For each index, update the environment variables as needed:

    * `PORT`: Specify the port number for the index to listen on.
    * `INDEX_TYPE`: Specify the type of Pinecone index to create. Accepted values: `serverless` or `pod`.
    * `VECTOR_TYPE`: Specify the [type of vectors](/guides/index-data/indexing-overview#indexes) you will store in the index. Accepted values: `dense` or `sparse`.

      <Note>Sparse is supported only with serverless indexes.</Note>
    * `DIMENSION`: Specify the dimension of vectors you will store in the index.

      <Note>For indexes that store only sparse vectors, this must be set to `0`.</Note>
    * `METRIC`: Specify the [distance metric](/guides/index-data/indexing-overview#distance-metrics) for calculating the similarity between vectors in the index. Accepted values when storing dense vectors: `cosine`, `euclidean`, or `dotproduct`. Accepted value when storing only sparse vectors: `dotproduct`.
  </Tab>
</Tabs>

### Database emulator

<Tabs>
  <Tab title="Docker Compose">
    Make sure [Docker](https://docs.docker.com/get-docker/) is installed and running on your local machine.

    Create a `docker-compose.yaml` file that defines a service for Pinecone local, including the `pinecone-local` Docker image, the host and port that Pinecone Local will run on and the range of ports that will be available for indexes:

    ```yaml theme={null}
    services:
      pinecone:
        image: ghcr.io/pinecone-io/pinecone-local:latest
        environment: 
          PORT: 5080
          PINECONE_HOST: localhost
        ports: 
          - "5080-5090:5080-5090"
        platform: linux/amd64
    ```

    To start Pinecone Local, run the following command:

    ```shell theme={null}
    docker compose up -d
    ```

    You'll see a message with details about the Pinecone Local instance.
  </Tab>

  <Tab title="Docker CLI">
    Make sure [Docker](https://docs.docker.com/get-docker/) is installed and running on your local machine.

    Download the latest `pinecone-local` Docker image:

    ```shell theme={null}
    docker pull ghcr.io/pinecone-io/pinecone-local:latest
    ```

    Start Pinecone Local:

    ```shell theme={null}
    docker run -d \
    --name pinecone-local \
    -e PORT=5080 \
    -e PINECONE_HOST=localhost \
    -p 5080-5090:5080-5090 \
    --platform linux/amd64 \
    ghcr.io/pinecone-io/pinecone-local:latest
    ```

    This command defines the host and port that Pinecone Local will run on, as well as the range of ports that will be available for indexes.
  </Tab>
</Tabs>

## 2. Develop your app

Running code against Pinecone Local is just like running code against your Pinecone account, with the following differences:

* Pinecone Local does not authenticate client requests. API keys are ignored.

* The latest version of Pinecone Local uses [Pinecone API version](/reference/api/versioning) `2025-01` and requires [Python SDK](/reference/sdks/python/overview) `v6.x` or later, [Node.js SDK](/reference/sdks/node/overview) `v5.x` or later, [Java SDK](/reference/sdks/java/overview) `v4.x` or later, and [Go SDK](/reference/sdks/go/overview) `v3.x` or later.

<Note>
  Be sure to review the [limitations](#limitations) of Pinecone Local before using it for development or testing.
</Note>

**Example**

The following example assumes that you have [started Pinecone Local without indexes](/guides/operations/local-development#database-emulator). It initializes a client, creates [an index for dense vectors](/guides/index-data/indexing-overview#indexes-with-dense-vectors) and [an index for sparse vectors](/guides/index-data/indexing-overview#indexes-with-sparse-vectors), upserts records into each, checks their record counts, and queries them.

<CodeGroup>
  ```python Python theme={null}
  from pinecone.grpc import PineconeGRPC, GRPCClientConfig
  from pinecone import ServerlessSpec

  # Initialize a client.
  # API key is required, but the value does not matter.
  # Host and port of the Pinecone Local instance
  # is required when starting without indexes. 
  pc = PineconeGRPC(
      api_key="pclocal", 
      host="http://localhost:5080" 
  )                                    

  # Create two indexes, one dense and one sparse
  dense_index_name = "dense-index"
  sparse_index_name = "sparse-index"

  if not pc.has_index(dense_index_name):  
      dense_index_model = pc.create_index(
          name=dense_index_name,
          vector_type="dense",
          dimension=2,
          metric="cosine",
          spec=ServerlessSpec(cloud="aws", region="us-east-1"),
          deletion_protection="disabled",
          tags={"environment": "development"}
      )

  print("Index model (dense):\n", dense_index_model)

  if not pc.has_index(sparse_index_name):  
      sparse_index_model = pc.create_index(
          name=sparse_index_name,
          vector_type="sparse",
          metric="dotproduct",
          spec=ServerlessSpec(cloud="aws", region="us-east-1"),
          deletion_protection="disabled",
          tags={"environment": "development"}
      )

  print("\nIndex model (sparse):\n", sparse_index_model)

  # Target each index, disabling tls
  dense_index_host = pc.describe_index(name=dense_index_name).host
  dense_index = pc.Index(host=dense_index_host, grpc_config=GRPCClientConfig(secure=False))
  sparse_index_host = pc.describe_index(name=sparse_index_name).host
  sparse_index = pc.Index(host=sparse_index_host, grpc_config=GRPCClientConfig(secure=False))

  # Upsert records into the index (dense)
  dense_index.upsert(
      vectors=[
          {
              "id": "vec1", 
              "values": [1.0, -2.5],
              "metadata": {"genre": "drama"}
          },
          {
              "id": "vec2", 
              "values": [3.0, -2.0],
              "metadata": {"genre": "documentary"}
          },
          {
              "id": "vec3", 
              "values": [0.5, -1.5],
              "metadata": {"genre": "documentary"}
          }
      ],
      namespace="example-namespace"
  )

  # Upsert records into the index (sparse)
  sparse_index.upsert(
      namespace="example-namespace",
      vectors=[
          {
              "id": "vec1",
              "sparse_values": {
                  "values": [1.7958984, 0.41577148, 2.828125, 2.8027344, 2.8691406, 1.6533203, 5.3671875, 1.3046875, 0.49780273, 0.5722656, 2.71875, 3.0820312, 2.5019531, 4.4414062, 3.3554688],
                  "indices": [822745112, 1009084850, 1221765879, 1408993854, 1504846510, 1596856843, 1640781426, 1656251611, 1807131503, 2543655733, 2902766088, 2909307736, 3246437992, 3517203014, 3590924191]
              },
              "metadata": {
                  "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.",
                  "category": "technology",
                  "quarter": "Q3"
              }
          },
          {
              "id": "vec2",
              "sparse_values": {
                  "values": [0.4362793, 3.3457031, 2.7714844, 3.0273438, 3.3164062, 5.6015625, 2.4863281, 0.38134766, 1.25, 2.9609375, 0.34179688, 1.4306641, 0.34375, 3.3613281, 1.4404297, 2.2558594, 2.2597656, 4.8710938, 0.5605469],
                  "indices": [131900689, 592326839, 710158994, 838729363, 1304885087, 1640781426, 1690623792, 1807131503, 2066971792, 2428553208, 2548600401, 2577534050, 3162218338, 3319279674, 3343062801, 3476647774, 3485013322, 3517203014, 4283091697]
              },
              "metadata": {
                  "chunk_text": "Analysts suggest that AAPL'\''s upcoming Q4 product launch event might solidify its position in the premium smartphone market.",
                  "category": "technology",
                  "quarter": "Q4"
              }
          },
          {
              "id": "vec3",
              "sparse_values": {
                  "values": [2.6875, 4.2929688, 3.609375, 3.0722656, 2.1152344, 5.78125, 3.7460938, 3.7363281, 1.2695312, 3.4824219, 0.7207031, 0.0826416, 4.671875, 3.7011719, 2.796875, 0.61621094],
                  "indices": [8661920, 350356213, 391213188, 554637446, 1024951234, 1640781426, 1780689102, 1799010313, 2194093370, 2632344667, 2641553256, 2779594451, 3517203014, 3543799498, 3837503950, 4283091697]
              },
              "metadata": {
                  "chunk_text": "AAPL'\''s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production",
                  "category": "technology",
                  "quarter": "Q3"
              }
          }
      ]
  )

  # Check the number of records in each index
  print("\nIndex stats (dense):\n", dense_index.describe_index_stats())
  print("\nIndex stats (sparse):\n", sparse_index.describe_index_stats())

  # Query the index (dense) with a metadata filter
  dense_response = dense_index.query(
      namespace="example-namespace",
      vector=[3.0, -2.0],
      filter={"genre": {"$eq": "documentary"}},
      top_k=1,
      include_values=False,
      include_metadata=True
  )

  print("\nDense query response:\n", dense_response)

  # Query the index (sparse) with a metadata filter
  sparse_response = sparse_index.query(
      namespace="example-namespace",
      sparse_vector={
        "values": [1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0],
        "indices": [767227209, 1640781426, 1690623792, 2021799277, 2152645940, 2295025838, 2443437770, 2779594451, 2956155693, 3476647774, 3818127854, 4283091697]
      }, 
      filter={
          "quarter": {"$eq": "Q4"}
      },
      top_k=1,
      include_values=False,
      include_metadata=True
  )

  print("/nSparse query response:\n", sparse_response)

  # Delete the indexes
  pc.delete_index(name=dense_index_name)
  pc.delete_index(name=sparse_index_name)
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone';

  // Initialize a client.
  // API key is required, but the value does not matter.
  // Host and port of the Pinecone Local instance
  // is required when starting without indexes.
  const pc = new Pinecone({ 
      apiKey: 'pclocal', 
      controllerHostUrl: 'http://localhost:5080' 
  });

  // Create two indexes, one dense and one sparse
  const denseIndexName = 'dense-index';
  const sparseIndexName = 'sparse-index';

  const denseIndexModel = await pc.createIndex({
    name: denseIndexName,
    vectorType: 'dense',
    dimension: 2,
    metric: 'cosine',
    spec: {
      serverless: {
        cloud: 'aws',
        region: 'us-east-1'
      }
    },
    deletionProtection: 'disabled',
    tags: { environment: 'development' }, 
  });

  console.log('Index model (dense):', denseIndexModel);

  const sparseIndexModel = await pc.createIndex({
      name: sparseIndexName,
      vectorType: 'sparse',
      metric: 'dotproduct',
      spec: {
        serverless: {
          cloud: 'aws',
          region: 'us-east-1'
        }
      },
      deletionProtection: 'disabled',
      tags: { environment: 'development' }, 
    });
    
  console.log('\nIndex model (sparse):', sparseIndexModel);
    
  // Target each index
  const denseIndexHost = (await pc.describeIndex(denseIndexName)).host;
  const denseIndex = await pc.index(denseIndexName, 'http://' + denseIndexHost);
  const sparseIndexHost = (await pc.describeIndex(sparseIndexName)).host;
  const sparseIndex = await pc.index(sparseIndexName, 'http://' + sparseIndexHost);

  // Upsert records into the index (dense)
  await denseIndex.namespace('example-namespace').upsert([
      {
          id: 'vec1', 
          values: [1.0, -2.5],
          metadata: { genre: 'drama' },
      },
      {
          id: 'vec2', 
          values: [3.0, -2.0],
          metadata: { genre: 'documentary' },
      },
      {
          id: 'vec3', 
          values: [0.5, -1.5],
          metadata: { genre: 'documentary' },
      }
  ]);

  // Upsert records into the index (sparse)
  await sparseIndex.namespace('example-namespace').upsert([
      {
          id: 'vec1',
          sparseValues: {
              indices: [822745112, 1009084850, 1221765879, 1408993854, 1504846510, 1596856843, 1640781426, 1656251611, 1807131503, 2543655733, 2902766088, 2909307736, 3246437992, 3517203014, 3590924191],
              values: [1.7958984, 0.41577148, 2.828125, 2.8027344, 2.8691406, 1.6533203, 5.3671875, 1.3046875, 0.49780273, 0.5722656, 2.71875, 3.0820312, 2.5019531, 4.4414062, 3.3554688]
          },
          metadata: { 
              chunk_text: 'AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.', 
              category: 'technology',
              quarter: 'Q3' 
          }
      },
      {
          id: 'vec2',
          sparseValues: {
              indices: [131900689, 592326839, 710158994, 838729363, 1304885087, 1640781426, 1690623792, 1807131503, 2066971792, 2428553208, 2548600401, 2577534050, 3162218338, 3319279674, 3343062801, 3476647774, 3485013322, 3517203014, 4283091697],
              values: [0.4362793, 3.3457031, 2.7714844, 3.0273438, 3.3164062, 5.6015625, 2.4863281, 0.38134766, 1.25, 2.9609375, 0.34179688, 1.4306641, 0.34375, 3.3613281, 1.4404297, 2.2558594, 2.2597656, 4.8710938, 0.5605469]
          },
          metadata: { 
              chunk_text: "Analysts suggest that AAPL's upcoming Q4 product launch event might solidify its position in the premium smartphone market.", 
              category: 'technology',
              quarter: 'Q4' 
          }
      },
      {
          id: 'vec3',
          sparseValues: {
              indices: [8661920, 350356213, 391213188, 554637446, 1024951234, 1640781426, 1780689102, 1799010313, 2194093370, 2632344667, 2641553256, 2779594451, 3517203014, 3543799498, 3837503950, 4283091697],
              values: [2.6875, 4.2929688, 3.609375, 3.0722656, 2.1152344, 5.78125, 3.7460938, 3.7363281, 1.2695312, 3.4824219, 0.7207031, 0.0826416, 4.671875, 3.7011719, 2.796875, 0.61621094]
          },
          metadata: { 
              chunk_text: "AAPL's strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production", 
              category: 'technology',
              quarter: 'Q3' 
          }
      }
  ]);
    
  // Check the number of records in each index
  console.log('\nIndex stats (dense):', await denseIndex.describeIndexStats());
  console.log('\nIndex stats (sparse):', await sparseIndex.describeIndexStats());

  // Query the index (dense) with a metadata filter
  const denseQueryResponse = await denseIndex.namespace('example-namespace').query({
      vector: [3.0, -2.0],
      filter: {
          'genre': {'$eq': 'documentary'}
      },
      topK: 1,
      includeValues: false,
      includeMetadata: true,
  });

  console.log('\nDense query response:', denseQueryResponse);

  const sparseQueryResponse = await sparseIndex.namespace('example-namespace').query({
      sparseVector: {
          indices: [767227209, 1640781426, 1690623792, 2021799277, 2152645940, 2295025838, 2443437770, 2779594451, 2956155693, 3476647774, 3818127854, 4283091697],
          values: [1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0]
      },
      topK: 1,
      includeValues: false,
      includeMetadata: true
  });

  console.log('\nSparse query response:', sparseQueryResponse);

  // Delete the index
  await pc.deleteIndex(denseIndexName);
  await pc.deleteIndex(sparseIndexName);
  ```

  ```java Java theme={null}
  import com.google.protobuf.Struct;
  import com.google.protobuf.Value;
  import io.pinecone.clients.Index;
  import io.pinecone.clients.Pinecone;
  import io.pinecone.proto.DescribeIndexStatsResponse;
  import org.openapitools.db_control.client.model.DeletionProtection;
  import io.pinecone.unsigned_indices_model.QueryResponseWithUnsignedIndices;

  import java.util.*;

  public class PineconeLocalExample {
      public static void main(String[] args) {
          // Initialize a client.
          // API key is required, but the value does not matter.
          // When starting without indexes, disable TLS and
          // provide the host and port of the Pinecone Local instance.
          String host = "http://localhost:5080";
          Pinecone pc = new Pinecone.Builder("pclocal")
                  .withHost(host)
                  .withTlsEnabled(false)
                  .build();

          // Create two indexes, one dense and one sparse
          String denseIndexName = "dense-index";
          String sparseIndexName = "sparse-index";
          HashMap<String, String> tags = new HashMap<>();
          tags.put("environment", "development");
          pc.createServerlessIndex(
                  denseIndexName,
                  "cosine",
                  2,
                  "aws",
                  "us-east-1",
                  DeletionProtection.DISABLED,
                  tags
          );
          pc.createSparseServelessIndex(
                  sparseIndexName,
                  "aws",
                  "us-east-1",
                  DeletionProtection.DISABLED,
                  tags,
                  "sparse"
          );

          // Get index connection objects
          Index denseIndexConnection = pc.getIndexConnection(denseIndexName);
          Index sparseIndexConnection = pc.getIndexConnection(sparseIndexName);

          // Upsert records into the index (dense)
          Struct metaData1 = Struct.newBuilder()
                  .putFields("genre", Value.newBuilder().setStringValue("drama").build())
                  .build();
          Struct metaData2 = Struct.newBuilder()
                  .putFields("genre", Value.newBuilder().setStringValue("documentary").build())
                  .build();
          Struct metaData3 = Struct.newBuilder()
                  .putFields("genre", Value.newBuilder().setStringValue("documentary").build())
                  .build();

          denseIndexConnection.upsert("vec1", Arrays.asList(1.0f, -2.5f),  null, null, metaData1, "example-namespace");
          denseIndexConnection.upsert("vec2", Arrays.asList(3.0f, -2.0f),  null, null, metaData2, "example-namespace");
          denseIndexConnection.upsert("vec3", Arrays.asList(0.5f, -1.5f),  null, null, metaData3, "example-namespace");

          // Upsert records into the index (sparse)
          ArrayList<Long> indices1 = new ArrayList<>(Arrays.asList(
                  822745112L, 1009084850L, 1221765879L, 1408993854L, 1504846510L,
                  1596856843L, 1640781426L, 1656251611L, 1807131503L, 2543655733L,
                  2902766088L, 2909307736L, 3246437992L, 3517203014L, 3590924191L
          ));

          ArrayList<Float> values1 = new ArrayList<>(Arrays.asList(
                  1.7958984f, 0.41577148f, 2.828125f, 2.8027344f, 2.8691406f,
                  1.6533203f, 5.3671875f, 1.3046875f, 0.49780273f, 0.5722656f,
                  2.71875f, 3.0820312f, 2.5019531f, 4.4414062f, 3.3554688f
          ));

          Struct sparseMetaData1 = Struct.newBuilder()
                  .putFields("chunk_text", Value.newBuilder().setStringValue("AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.").build())
                  .putFields("category", Value.newBuilder().setStringValue("technology").build())
                  .putFields("quarter", Value.newBuilder().setStringValue("Q3").build())
                  .build();

          ArrayList<Long> indices2 = new ArrayList<>(Arrays.asList(
                  131900689L, 592326839L, 710158994L, 838729363L, 1304885087L,
                  1640781426L, 1690623792L, 1807131503L, 2066971792L, 2428553208L,
                  2548600401L, 2577534050L, 3162218338L, 3319279674L, 3343062801L,
                  3476647774L, 3485013322L, 3517203014L, 4283091697L
          ));

          ArrayList<Float> values2 = new ArrayList<>(Arrays.asList(
                  0.4362793f, 3.3457031f, 2.7714844f, 3.0273438f, 3.3164062f,
                  5.6015625f, 2.4863281f, 0.38134766f, 1.25f, 2.9609375f,
                  0.34179688f, 1.4306641f, 0.34375f, 3.3613281f, 1.4404297f,
                  2.2558594f, 2.2597656f, 4.8710938f, 0.5605469f
          ));

          Struct sparseMetaData2 = Struct.newBuilder()
                  .putFields("chunk_text", Value.newBuilder().setStringValue("Analysts suggest that AAPL'\\''s upcoming Q4 product launch event might solidify its position in the premium smartphone market.").build())
                  .putFields("category", Value.newBuilder().setStringValue("technology").build())
                  .putFields("quarter", Value.newBuilder().setStringValue("Q4").build())
                  .build();

          ArrayList<Long> indices3 = new ArrayList<>(Arrays.asList(
                  8661920L, 350356213L, 391213188L, 554637446L, 1024951234L,
                  1640781426L, 1780689102L, 1799010313L, 2194093370L, 2632344667L,
                  2641553256L, 2779594451L, 3517203014L, 3543799498L,
                  3837503950L, 4283091697L
          ));

          ArrayList<Float> values3 = new ArrayList<>(Arrays.asList(
                  2.6875f, 4.2929688f, 3.609375f, 3.0722656f, 2.1152344f,
                  5.78125f, 3.7460938f, 3.7363281f, 1.2695312f, 3.4824219f,
                  0.7207031f, 0.0826416f, 4.671875f, 3.7011719f, 2.796875f,
                  0.61621094f
          ));

          Struct sparseMetaData3 = Struct.newBuilder()
                  .putFields("chunk_text", Value.newBuilder().setStringValue("AAPL'\\''s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production").build())
                  .putFields("category", Value.newBuilder().setStringValue("technology").build())
                  .putFields("quarter", Value.newBuilder().setStringValue("Q3").build())
                  .build();

          sparseIndexConnection.upsert("vec1", Collections.emptyList(), indices1, values1, sparseMetaData1, "example-namespace");
          sparseIndexConnection.upsert("vec2", Collections.emptyList(), indices2, values2, sparseMetaData2, "example-namespace");
          sparseIndexConnection.upsert("vec3", Collections.emptyList(), indices3, values3, sparseMetaData3, "example-namespace");

          // Check the number of records each the index
          DescribeIndexStatsResponse denseIndexStatsResponse = denseIndexConnection.describeIndexStats(null);
          System.out.println("Index stats (dense):");
          System.out.println(denseIndexStatsResponse);
          DescribeIndexStatsResponse sparseIndexStatsResponse = sparseIndexConnection.describeIndexStats(null);
          System.out.println("Index stats (sparse):");
          System.out.println(sparseIndexStatsResponse);

          // Query the index (dense) with a metadata filter
          List<Float> queryVector = Arrays.asList(1.0f, 1.5f);
          QueryResponseWithUnsignedIndices denseQueryResponse = denseIndexConnection.query(1, queryVector, null, null, null, "example-namespace", null, false, true);
          System.out.println("Dense query response:");
          System.out.println(denseQueryResponse);

          // Query the index (sparse) with a metadata filter
          List<Long> sparseIndices = Arrays.asList(
                  767227209L, 1640781426L, 1690623792L, 2021799277L, 2152645940L,
                  2295025838L, 2443437770L, 2779594451L, 2956155693L, 3476647774L,
                  3818127854L, 428309169L);
          List<Float> sparseValues = Arrays.asList(
                  1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f,
                  1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f);

          QueryResponseWithUnsignedIndices sparseQueryResponse = sparseIndexConnection.query(1, null, sparseIndices, sparseValues, null, "example-namespace", null, false, true);
          System.out.println("Sparse query response:");
          System.out.println(sparseQueryResponse);

          // Delete the indexes
          pc.deleteIndex(denseIndexName);
          pc.deleteIndex(sparseIndexName);
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
  	"context"
  	"encoding/json"
  	"fmt"
  	"log"

  	"github.com/pinecone-io/go-pinecone/v4/pinecone"
  	"google.golang.org/protobuf/types/known/structpb"
  )

  func prettifyStruct(obj interface{}) string {
  	bytes, _ := json.MarshalIndent(obj, "", "  ")
  	return string(bytes)
  }

  func main() {
  	ctx := context.Background()

  	// Initialize a client.
  	// No API key is required.
  	// Host and port of the Pinecone Local instance
  	// is required when starting without indexes.
  	pc, err := pinecone.NewClientBase(pinecone.NewClientBaseParams{
  		Host: "http://localhost:5080",
  	})
  	if err != nil {
  		log.Fatalf("Failed to create Client: %v", err)
  	}

  	// Create two indexes, one dense and one sparse
  	denseIndexName := "dense-index"
  	denseVectorType := "dense"
  	dimension := int32(2)
  	denseMetric := pinecone.Cosine
  	deletionProtection := pinecone.DeletionProtectionDisabled
  	denseIdx, err := pc.CreateServerlessIndex(ctx, &pinecone.CreateServerlessIndexRequest{
  		Name:               denseIndexName,
  		VectorType:         &denseVectorType,
  		Dimension:          &dimension,
  		Metric:             &denseMetric,
  		Cloud:              pinecone.Aws,
  		Region:             "us-east-1",
  		DeletionProtection: &deletionProtection,
  		Tags:               &pinecone.IndexTags{"environment": "development"},
  	})
  	if err != nil {
  		log.Fatalf("Failed to create serverless index: %v", denseIdx.Name)
  	} else {
  		fmt.Printf("Successfully created serverless index: %v\n", denseIdx.Name)
  	}

  	sparseIndexName := "sparse-index"
  	sparseVectorType := "sparse"
  	sparseMetric := pinecone.Dotproduct
  	sparseIdx, err := pc.CreateServerlessIndex(ctx, &pinecone.CreateServerlessIndexRequest{
  		Name:               sparseIndexName,
  		VectorType:         &sparseVectorType,
  		Metric:             &sparseMetric,
  		Cloud:              pinecone.Aws,
  		Region:             "us-east-1",
  		DeletionProtection: &deletionProtection,
  		Tags:               &pinecone.IndexTags{"environment": "development"},
  	})
  	if err != nil {
  		log.Fatalf("Failed to create serverless index: %v", sparseIdx.Name)
  	} else {
  		fmt.Printf("\nSuccessfully created serverless index: %v\n", sparseIdx.Name)
  	}

  	// Get the index hosts
  	denseIdxModel, err := pc.DescribeIndex(ctx, denseIndexName)
  	if err != nil {
  		log.Fatalf("Failed to describe index \"%v\": %v", denseIndexName, err)
  	}

  	sparseIdxModel, err := pc.DescribeIndex(ctx, sparseIndexName)
  	if err != nil {
  		log.Fatalf("Failed to describe index \"%v\": %v", sparseIndexName, err)
  	}

  	// Target the indexes.
  	// Make sure to prefix the hosts with http:// to let the SDK know to disable tls.
  	denseIdxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "http://" + denseIdxModel.Host, Namespace: "example-namespace"})
  	if err != nil {
  		log.Fatalf("Failed to create IndexConnection for Host: %v", err)
  	}

  	sparseIdxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "http://" + sparseIdxModel.Host, Namespace: "example-namespace"})
  	if err != nil {
  		log.Fatalf("Failed to create IndexConnection for Host: %v", err)
  	}

  	// Upsert records into the index (dense)
  	denseMetadataMap1 := map[string]interface{}{
  		"genre": "drama",
  	}

  	denseMetadata1, err := structpb.NewStruct(denseMetadataMap1)
  	if err != nil {
  		log.Fatalf("Failed to create metadata map: %v", err)
  	}

  	denseMetadataMap2 := map[string]interface{}{
  		"genre": "documentary",
  	}

  	denseMetadata2, err := structpb.NewStruct(denseMetadataMap2)
  	if err != nil {
  		log.Fatalf("Failed to create metadata map: %v", err)
  	}

  	denseMetadataMap3 := map[string]interface{}{
  		"genre": "documentary",
  	}

  	denseMetadata3, err := structpb.NewStruct(denseMetadataMap3)
  	if err != nil {
  		log.Fatalf("Failed to create metadata map: %v", err)
  	}

  	denseVectors := []*pinecone.Vector{
  		{
  			Id:       "vec1",
  			Values:   &[]float32{1.0, -2.5},
  			Metadata: denseMetadata1,
  		},
  		{
  			Id:       "vec2",
  			Values:   &[]float32{3.0, -2.0},
  			Metadata: denseMetadata2,
  		},
  		{
  			Id:       "vec3",
  			Values:   &[]float32{0.5, -1.5},
  			Metadata: denseMetadata3,
  		},
  	}

  	denseCount, err := denseIdxConnection.UpsertVectors(ctx, denseVectors)
  	if err != nil {
  		log.Fatalf("Failed to upsert vectors: %v", err)
  	} else {
  		fmt.Printf("\nSuccessfully upserted %d vector(s)!\n", denseCount)
  	}

  	// Upsert records into the index (sparse)
  	sparseValues1 := pinecone.SparseValues{
  		Indices: []uint32{822745112, 1009084850, 1221765879, 1408993854, 1504846510, 1596856843, 1640781426, 1656251611, 1807131503, 2543655733, 2902766088, 2909307736, 3246437992, 3517203014, 3590924191},
  		Values:  []float32{1.7958984, 0.41577148, 2.828125, 2.8027344, 2.8691406, 1.6533203, 5.3671875, 1.3046875, 0.49780273, 0.5722656, 2.71875, 3.0820312, 2.5019531, 4.4414062, 3.3554688},
  	}

  	sparseMetadataMap1 := map[string]interface{}{
  		"chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones",
  		"category":   "technology",
  		"quarter":    "Q3",
  	}

  	sparseMetadata1, err := structpb.NewStruct(sparseMetadataMap1)
  	if err != nil {
  		log.Fatalf("Failed to create metadata map: %v", err)
  	}

  	sparseValues2 := pinecone.SparseValues{
  		Indices: []uint32{131900689, 592326839, 710158994, 838729363, 1304885087, 1640781426, 1690623792, 1807131503, 2066971792, 2428553208, 2548600401, 2577534050, 3162218338, 3319279674, 3343062801, 3476647774, 3485013322, 3517203014, 4283091697},
  		Values:  []float32{0.4362793, 3.3457031, 2.7714844, 3.0273438, 3.3164062, 5.6015625, 2.4863281, 0.38134766, 1.25, 2.9609375, 0.34179688, 1.4306641, 0.34375, 3.3613281, 1.4404297, 2.2558594, 2.2597656, 4.8710938, 0.560546},
  	}

  	sparseMetadataMap2 := map[string]interface{}{
  		"chunk_text": "Analysts suggest that AAPL's upcoming Q4 product launch event might solidify its position in the premium smartphone market.",
  		"category":   "technology",
  		"quarter":    "Q4",
  	}

  	sparseMetadata2, err := structpb.NewStruct(sparseMetadataMap2)
  	if err != nil {
  		log.Fatalf("Failed to create metadata map: %v", err)
  	}

  	sparseValues3 := pinecone.SparseValues{
  		Indices: []uint32{8661920, 350356213, 391213188, 554637446, 1024951234, 1640781426, 1780689102, 1799010313, 2194093370, 2632344667, 2641553256, 2779594451, 3517203014, 3543799498, 3837503950, 4283091697},
  		Values:  []float32{2.6875, 4.2929688, 3.609375, 3.0722656, 2.1152344, 5.78125, 3.7460938, 3.7363281, 1.2695312, 3.4824219, 0.7207031, 0.0826416, 4.671875, 3.7011719, 2.796875, 0.61621094},
  	}

  	sparseMetadataMap3 := map[string]interface{}{
  		"chunk_text": "AAPL's strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production",
  		"category":   "technology",
  		"quarter":    "Q3",
  	}

  	sparseMetadata3, err := structpb.NewStruct(sparseMetadataMap3)
  	if err != nil {
  		log.Fatalf("Failed to create metadata map: %v", err)
  	}

  	sparseVectors := []*pinecone.Vector{
  		{
  			Id:           "vec1",
  			SparseValues: &sparseValues1,
  			Metadata:     sparseMetadata1,
  		},
  		{
  			Id:           "vec2",
  			SparseValues: &sparseValues2,
  			Metadata:     sparseMetadata2,
  		},
  		{
  			Id:           "vec3",
  			SparseValues: &sparseValues3,
  			Metadata:     sparseMetadata3,
  		},
  	}

  	sparseCount, err := sparseIdxConnection.UpsertVectors(ctx, sparseVectors)
  	if err != nil {
  		log.Fatalf("Failed to upsert vectors: %v", err)
  	} else {
  		fmt.Printf("\nSuccessfully upserted %d vector(s)!\n", sparseCount)
  	}

  	// Check the number of records in each index
  	denseStats, err := denseIdxConnection.DescribeIndexStats(ctx)
  	if err != nil {
  		log.Fatalf("Failed to describe index: %v", err)
  	} else {
  		fmt.Printf("\nIndex stats (dense): %+v\n", prettifyStruct(*denseStats))
  	}

  	sparseStats, err := sparseIdxConnection.DescribeIndexStats(ctx)
  	if err != nil {
  		log.Fatalf("Failed to describe index: %v", err)
  	} else {
  		fmt.Printf("\nIndex stats (sparse): %+v\n", prettifyStruct(*sparseStats))
  	}

  	// Query the index (dense) with a metadata filter
  	queryVector := []float32{3.0, -2.0}

  	queryMetadataMap := map[string]interface{}{
  		"genre": map[string]interface{}{
  			"$eq": "documentary",
  		},
  	}

  	metadataFilter, err := structpb.NewStruct(queryMetadataMap)
  	if err != nil {
  		log.Fatalf("Failed to create metadata map: %v", err)
  	}

  	denseRes, err := denseIdxConnection.QueryByVectorValues(ctx, &pinecone.QueryByVectorValuesRequest{
  		Vector:          queryVector,
  		TopK:            1,
  		MetadataFilter:  metadataFilter,
  		IncludeValues:   false,
  		IncludeMetadata: true,
  	})
  	if err != nil {
  		log.Fatalf("Error encountered when querying by vector: %v", err)
  	} else {
  		fmt.Printf("\nDense query response: %v\n", prettifyStruct(denseRes))
  	}

  	// Query the index (sparse) with a metadata filter

  	sparseValues := pinecone.SparseValues{
  		Indices: []uint32{767227209, 1640781426, 1690623792, 2021799277, 2152645940, 2295025838, 2443437770, 2779594451, 2956155693, 3476647774, 3818127854, 4283091697},
  		Values:  []float32{1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0},
  	}

  	sparseRes, err := sparseIdxConnection.QueryByVectorValues(ctx, &pinecone.QueryByVectorValuesRequest{
  		SparseValues:    &sparseValues,
  		TopK:            1,
  		IncludeValues:   false,
  		IncludeMetadata: true,
  	})
  	if err != nil {
  		log.Fatalf("Error encountered when querying by vector: %v", err)
  	} else {
  		fmt.Printf("\nSparse query response: %v\n", prettifyStruct(sparseRes))
  	}
  	// Delete the indexes
  	err = pc.DeleteIndex(ctx, denseIndexName)
  	if err != nil {
  		log.Fatalf("Failed to delete index: %v", err)
  	} else {
  		fmt.Printf("\nIndex \"%v\" deleted successfully\n", denseIndexName)
  	}

  	err = pc.DeleteIndex(ctx, sparseIndexName)
  	if err != nil {
  		log.Fatalf("Failed to delete index: %v", err)
  	} else {
  		fmt.Printf("\nIndex \"%v\" deleted successfully\n", sparseIndexName)
  	}
  }
  ```

  ```shell curl theme={null}
  PINECONE_LOCAL_HOST="localhost:5080"
  DENSE_INDEX_HOST="localhost:5081"
  SPARSE_INDEX_HOST="localhost:5082"

  # Create two indexes, one dense and one sparse
  curl -X POST "http://$PINECONE_LOCAL_HOST/indexes" \
      -H "Accept: application/json" \
      -H "Content-Type: application/json" \
      -H "X-Pinecone-Api-Version: 2025-10" \
      -d '{
              "name": "dense-index",
              "vector_type": "dense",
              "dimension": 2,
              "metric": "cosine",
              "spec": {
                  "serverless": {
                      "cloud": "aws",
                      "region": "us-east-1"
                  }
              },
              "tags": {
                  "environment": "development"
              },
              "deletion_protection": "disabled"
          }'

  curl -X POST "http://$PINECONE_LOCAL_HOST/indexes" \
      -H "Accept: application/json" \
      -H "Content-Type: application/json" \
      -H "X-Pinecone-Api-Version: 2025-10" \
      -d '{
              "name": "sparse-index",
              "vector_type": "sparse",
              "metric": "dotproduct",
              "spec": {
                  "serverless": {
                      "cloud": "aws",
                      "region": "us-east-1"
                  }
              },
              "tags": {
                  "environment": "development"
              },
              "deletion_protection": "disabled"
          }'

  # Upsert records into the index (dense)
  curl -X POST "http://$DENSE_INDEX_HOST/vectors/upsert" \
      -H "Content-Type: application/json" \
      -H "X-Pinecone-Api-Version: 2025-10" \
      -d '{
              "namespace": "example-namespace",
              "vectors": [
                  {
                      "id": "vec1", 
                      "values": [1.0, -2.5],
                      "metadata": {"genre": "drama"}
                  },
                  {
                      "id": "vec2", 
                      "values": [3.0, -2.0],
                      "metadata": {"genre": "documentary"}
                  },
                  {
                      "id": "vec3", 
                      "values": [0.5, -1.5],
                      "metadata": {"genre": "documentary"}
                  }
              ]
          }'

  # Upsert records into the index (sparse)
  curl -X POST "http://$SPARSE_INDEX_HOST/vectors/upsert" \
      -H "Content-Type: application/json" \
      -H "X-Pinecone-Api-Version: 2025-10" \
      -d '{
              "namespace": "example-namespace",
              "vectors": [
                  {
                      "id": "vec1",
                      "sparseValues": {
                          "values": [1.7958984, 0.41577148, 2.828125, 2.8027344, 2.8691406, 1.6533203, 5.3671875, 1.3046875, 0.49780273, 0.5722656, 2.71875, 3.0820312, 2.5019531, 4.4414062, 3.3554688],
                          "indices": [822745112, 1009084850, 1221765879, 1408993854, 1504846510, 1596856843, 1640781426, 1656251611, 1807131503, 2543655733, 2902766088, 2909307736, 3246437992, 3517203014, 3590924191]
                      },
                      "metadata": {
                          "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.",
                          "category": "technology",
                          "quarter": "Q3"
                      }
                  },
                  {
                      "id": "vec2",
                      "sparseValues": {
                          "values": [0.4362793, 3.3457031, 2.7714844, 3.0273438, 3.3164062, 5.6015625, 2.4863281, 0.38134766, 1.25, 2.9609375, 0.34179688, 1.4306641, 0.34375, 3.3613281, 1.4404297, 2.2558594, 2.2597656, 4.8710938, 0.5605469],
                          "indices": [131900689, 592326839, 710158994, 838729363, 1304885087, 1640781426, 1690623792, 1807131503, 2066971792, 2428553208, 2548600401, 2577534050, 3162218338, 3319279674, 3343062801, 3476647774, 3485013322, 3517203014, 4283091697]
                      },
                      "metadata": {
                          "chunk_text": "Analysts suggest that AAPL'\''s upcoming Q4 product launch event might solidify its position in the premium smartphone market.",
                          "category": "technology",
                          "quarter": "Q4"
                      }
                  },
                  {
                      "id": "vec3",
                      "sparseValues": {
                          "values": [2.6875, 4.2929688, 3.609375, 3.0722656, 2.1152344, 5.78125, 3.7460938, 3.7363281, 1.2695312, 3.4824219, 0.7207031, 0.0826416, 4.671875, 3.7011719, 2.796875, 0.61621094],
                          "indices": [8661920, 350356213, 391213188, 554637446, 1024951234, 1640781426, 1780689102, 1799010313, 2194093370, 2632344667, 2641553256, 2779594451, 3517203014, 3543799498, 3837503950, 4283091697]
                      },
                      "metadata": {
                          "chunk_text": "AAPL'\''s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production",
                          "category": "technology",
                          "quarter": "Q3"
                      }
                  }
              ]
          }'

  # Check the number of records in each index
  curl -X POST "http://$DENSE_INDEX_HOST/describe_index_stats" \
      -H "Content-Type: application/json" \
      -H "X-Pinecone-Api-Version: 2025-10" \
      -d '{}'

  curl -X POST "http://$SPARSE_INDEX_HOST/describe_index_stats" \
      -H "Content-Type: application/json" \
      -H "X-Pinecone-Api-Version: 2025-10" \
      -d '{}'

  # Query the index (dense) with a metadata filter
  curl "http://$DENSE_INDEX_HOST/query" \
      -H "Content-Type: application/json" \
      -H "X-Pinecone-Api-Version: 2025-10" \
      -d '{
              "vector": [3.0, -2.0],
              "filter": {"genre": {"$eq": "documentary"}},
              "topK": 1,
              "includeMetadata": true,
              "includeValues": false,
              "namespace": "example-namespace"
          }'

  # Query the index (sparse) with a metadata filter
  curl "http://$SPARSE_INDEX_HOST/query" \
      -H "Content-Type: application/json" \
      -H "X-Pinecone-Api-Version: 2025-10" \
      -d '{
              "sparseVector": {
                  "values": [1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0],
                  "indices": [767227209, 1640781426, 1690623792, 2021799277, 2152645940, 2295025838, 2443437770, 2779594451, 2956155693, 3476647774, 3818127854, 4283091697]
              },
              "filter": {"quarter": {"$eq": "Q4"}},
              "namespace": "example-namespace",
              "topK": 1,
              "includeMetadata": true,
              "includeValues": false
          }'

  # Delete the index
  curl -X DELETE "http://$PINECONE_LOCAL_HOST/indexes/dense-index" \
      -H "X-Pinecone-Api-Version: 2025-10"

  curl -X DELETE "http://$PINECONE_LOCAL_HOST/indexes/sparse-index" \
      -H "X-Pinecone-Api-Version: 2025-10"
  ```
</CodeGroup>

## 3. Stop Pinecone Local

<Warning>
  Pinecone Local is an in-memory emulator. Records loaded into Pinecone Local do not persist after Pinecone Local is stopped.
</Warning>

To stop and remove the resources for Pinecone Local, run the following command:

<CodeGroup>
  ```shell Docker Compose theme={null}
  docker compose down
  ```

  ```shell Docker CLI theme={null}
  # If you started Pinecone Local with indexes:
  docker stop dense-index sparse-index
  docker rm dense-index sparse-index

  # If you started Pinecone Local without indexes:
  docker stop pinecone-local
  docker rm pinecone-local
  ```
</CodeGroup>

## Moving from Pinecone Local to your Pinecone account

When you're ready to run your application against your Pinecone account, be sure to do the following:

* Update your application to [use your Pinecone API key](/reference/api/authentication).
* Update your application to [target your Pinecone indexes](/guides/manage-data/target-an-index).
* [Use Pinecone's import feature](/guides/index-data/import-data) to efficiently load large amounts of data into your indexes and then [use batch upserts](/guides/index-data/upsert-data#upsert-in-batches) for ongoing writes.
* Follow Pinecone's [production best practices](/guides/production/production-checklist).


# Use the Pinecone MCP server
Source: https://docs.pinecone.io/guides/operations/mcp-server

Connect AI agents to Pinecone through the MCP server to search docs, manage indexes, and query data from Claude, Cursor, Antigravity, or Claude Code.

The Pinecone MCP server enables AI agents to interact directly with Pinecone's functionality and documentation via the standardized [Model Context Protocol (MCP)](https://modelcontextprotocol.io/). Using the MCP server, agents can search Pinecone documentation, manage indexes, upsert data, and query indexes for relevant information.

This page shows you how to configure [Antigravity](https://antigravity.google/), [Claude Desktop](https://claude.ai/download), [Claude Code](https://claude.ai/code), and [Cursor](https://www.cursor.com/) to connect with the Pinecone MCP server.

<Note>
  Pinecone also provides a dedicated MCP server for each [Pinecone Assistant](/guides/assistant/overview), giving AI agents direct access to context from that assistant's uploaded files. The assistant MCP server is available as a managed remote endpoint or as a self-hosted Docker container that you can extend and run in your own infrastructure. See [Use an Assistant MCP server](/guides/assistant/mcp-server).
</Note>

<Tip>
  Pinecone also offers plugins and extensions with built-in skills for agentic IDEs and CLIs. See [Agentic IDEs and CLIs](/guides/get-started/ai-coding-tools) for an overview, or jump directly to the [Claude Code plugin](/integrations/claude-code), [Gemini CLI extension](/integrations/gemini-cli), [Cursor plugin](/integrations/cursor), or [Agent Skills](/integrations/agent-skills) for GitHub Copilot and other IDEs.
</Tip>

## Tools

The Pinecone MCP server provides the following tools:

* `search-docs`: Search the official Pinecone documentation.
* `list-indexes`: Lists all Pinecone indexes.
* `describe-index`: Describes the configuration of an index.
* `describe-index-stats`: Provides statistics about the data in the index, including the  number of records and available namespaces.
* `create-index-for-model`: Creates a new index that uses an integrated inference model to embed text as vectors.
* `upsert-records`: Inserts or updates records in an index with integrated inference.
* `search-records`: Searches for records in an index based on a text query, using integrated inference for embedding. Has options for metadata filtering and reranking.
* `cascading-search`: Searches for records across multiple indexes, deduplicating and reranking the results.
* `rerank-documents`: Reranks a collection of records or text documents using a specialized reranking model.

<Note>
  The Pinecone MCP supports only [indexes with integrated embedding](/guides/index-data/indexing-overview#vector-embedding). Indexes for vectors you create with external embedding models are not supported.
</Note>

## Before you begin

Ensure you have the following:

* A [Pinecone API key](https://app.pinecone.io/organizations/-/keys)
* [Node.js](https://nodejs.org/en) installed, with `node` and `npx` available on your `PATH`

## Configure Antigravity

Antigravity supports MCP via its built-in MCP Store. You can install the Pinecone server from the store or add it via the raw config.

<Steps>
  <Step title="Add the MCP server">
    **Install from the MCP Store**

    1. Open the **MCP Store** via the "..." dropdown at the top of the editor's agent panel.
    2. Find **Pinecone** in the list of supported servers and click **Install**.
    3. Follow the on-screen prompts to authenticate and set your Pinecone API key.

    **Add via raw config**

    1. Open the MCP Store via the "..." dropdown at the top of the editor's agent panel.
    2. Click **Manage MCP Servers**, then **View raw config**.
    3. Edit `mcp_config.json` and add the Pinecone server:

    ```json theme={null}
    {
      "mcpServers": {
        "pinecone": {
          "command": "npx",
          "args": [
            "-y", "@pinecone-database/mcp"
          ],
          "env": {
            "PINECONE_API_KEY": "{{YOUR_API_KEY}}"
          }
        }
      }
    }
    ```

    Replace `YOUR_API_KEY` with your [Pinecone API key](https://app.pinecone.io/organizations/-/keys).
  </Step>

  <Step title="Check the status">
    After installing or saving the config, the Pinecone server and its tools should appear in the agent panel. Use the MCP tools list to confirm the server is connected.
  </Step>

  <Step title="Test the server">
    In the agent chat, try prompts that use Pinecone. For example, try generating code that creates an index, upserts records, or searches the index. The AI can use the connected MCP server for context and actions.
  </Step>
</Steps>

## Configure Claude Code

<Tip>
  For the easiest setup, install the [Pinecone Claude Code plugin](/integrations/claude-code) instead — it bundles the MCP server, 8 skills, and slash commands. The manual configuration below is for users who only want the MCP server.
</Tip>

<Steps>
  <Step title="Add the MCP server">
    Run the following command to add the Pinecone MCP server to your Claude Code instance:

    ```bash theme={null}
    claude mcp add-json pinecone-mcp \
      '{"type": "stdio",
        "command": "npx",
        "args": ["-y", "@pinecone-database/mcp"],
        "env": {"PINECONE_API_KEY": "YOUR_API_KEY"}}'
    ```
  </Step>

  <Step title="Check the status">
    Restart Claude Code. Then, run the `/mcp` command to check the status of the Pinecone MCP. You should see the following:

    ```bash theme={null}
      > /mcp 
        ⎿  MCP Server Status

          • pinecone-mcp: ✓ connected

    ```
  </Step>

  <Step title="Test the server">
    Test the Pinecone MCP server with prompts to Claude Code that require the server to generate Pinceone-compatible code and perform tasks in your Pinecone account.

    Generate code:

    > Write a Python script that creates an index for dense vectors with integrated embedding, upserts 20 sentences about dogs, waits 10 seconds, searches the index, and reranks the results.

    Perform tasks:

    > Create an index for dense vectors with integrated embedding, upsert 20 sentences about dogs, waits 10 seconds, search the index, and reranks the results.
  </Step>
</Steps>

## Configure Claude Desktop

<Steps>
  <Step title="Add the MCP server">
    Go to **Settings > Developer > Edit Config** and add the following configuration:

    ```json theme={null}
    {
      "mcpServers": {
        "pinecone": {
          "command": "npx",
          "args": [
            "-y", "@pinecone-database/mcp"
          ],
          "env": {
            "PINECONE_API_KEY": "YOUR_API_KEY"
          }
        }
      }
    }
    ```

    Replace `YOUR_API_KEY` with your Pinecone API key.
  </Step>

  <Step title="Check the status">
    Restart Claude Desktop. On the new chat screen, you should see a hammer (MCP) icon appear with the new MCP tools available.
  </Step>

  <Step title="Test the server">
    Test the Pinecone MCP server with prompts that required the server to generate Pinceone-compatible code and perform tasks in your Pinecone account.

    Generate code:

    > Write a Python script that creates an index for dense vectors with integrated embedding, upserts 20 sentences about dogs, waits 10 seconds, searches the index, and reranks the results.

    Perform tasks:

    > Create an index for dense vectors with integrated embedding, upsert 20 sentences about dogs, waits 10 seconds, search the index, and reranks the results.
  </Step>
</Steps>

## Configure Cursor

<Tip>
  For the easiest setup, install the [Pinecone Cursor plugin](/integrations/cursor) instead — it bundles the MCP server, 8 skills, and slash commands. The manual configuration below is for users who only want the MCP server.
</Tip>

<Steps>
  <Step title="Add the MCP server">
    In your project root, create a `.cursor/mcp.json` file, if it doesn't exist, and add the following configuration:

    ```json theme={null}
    {
      "mcpServers": {
        "pinecone": {
          "command": "npx",
          "args": [
            "-y", "@pinecone-database/mcp"
          ],
          "env": {
            "PINECONE_API_KEY": "{{YOUR_API_KEY}}"
          }
        }
      }
    }
    ```
  </Step>

  <Step title="Check the status">
    Go to **Cursor Settings > MCP**. You should see the server and its list of tools.
  </Step>

  <Step title="Add Pinecone rules">
    The Pinecone MCP server works well out of the box. However, you can add explicit rules to ensure the server behaves as you expect.

    In your project root, create a `.cursor/rules/pinecone.mdc` file and add the following:

    ```mdx [expandable] theme={null}
    ### Tool Usage for Code Generation

    - When generating code related to Pinecone, always use the `pinecone` MCP and the `search_docs` tool.

    - Perform at least two distinct searches per request using different, relevant questions to ensure comprehensive context is gathered before writing code.

    ### Error Handling

    - If an error occurs while executing Pinecone-related code, immediately invoke the `pinecone` MCP and the `search_docs` tool.

    - Search for guidance on the specific error encountered and incorporate any relevant findings into your resolution strategy.

    ### Syntax and Version Accuracy

    - Before writing any code, verify and use the correct syntax for the latest stable version of the Pinecone SDK.

    - Prefer official code snippets and examples from documentation over generated or assumed field values.

    - Do not fabricate field names, parameter values, or request formats.

    ### SDK Installation Best Practices

    - When providing installation instructions, always reference the current official package name.

    - For Pinecone, use `pip install pinecone` not deprecated packages like `pinecone-client`.
    ```
  </Step>

  <Step title="Test the server">
    Press `Command + i` to open the Agent chat. Test the Pinecone MCP server with prompts that required the server to generate Pinceone-compatible code and perform tasks in your Pinecone account.

    Generate code:

    > Write a Python script that creates an index for dense vectors with integrated embedding, upserts 20 sentences about dogs, waits 10 seconds, searches the index, and reranks the results.

    Perform tasks:

    > Create an index for dense vectors with integrated embedding, upsert 20 sentences about dogs, waits 10 seconds, search the index, and reranks the results.
  </Step>
</Steps>


# Decrease latency
Source: https://docs.pinecone.io/guides/optimize/decrease-latency

Reduce query and upsert latency in Pinecone using namespaces, metadata filters, targeting indexes by host, and regional colocation strategies.

## Use namespaces

When you divide records into [namespaces](/guides/index-data/indexing-overview#namespaces) in a logical way, you speed up queries by ensuring only relevant records are scanned. The same applies to [fetching records](/guides/manage-data/fetch-data), [listing record IDs](/guides/manage-data/list-record-ids), and other data operations.

## Filter by metadata

In addition to increasing search accuracy and relevance, [searching with metadata filters](/guides/search/filter-by-metadata) can also help decrease latency by retrieving only records that match the filter.

## Target indexes by host

When you target an index by name for data operations such as `upsert` and `query`, the SDK gets the unique DNS host for the index using the `describe_index` operation. This is convenient for testing but should be avoided in production because `describe_index` uses a different API than data operations and therefore adds an additional network call and point of failure. Instead, you should get an index host once and cache it for reuse or specify the host directly.

You can get index hosts in the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/indexes) or using the [`describe_index`](/guides/manage-data/manage-indexes#describe-an-index) operation.

The following example shows how to target an index by host directly:

<Note>
  When using Private Endpoints for private connectivity between your application and Pinecone, you must target the index using the [Private Endpoint URL](/guides/production/configure-private-endpoints#read-and-write-data) for the host.
</Note>

<CodeGroup>
  ```Python Python {5} theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")

  index = pc.Index(host="INDEX_HOST")
  ```

  ```javascript JavaScript {6} theme={null}
  import { Pinecone } from '@pinecone-database/pinecone';

  const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' });

  // For the Node.js SDK, you must specify both the index host and name.
  const index = pc.index("INDEX_NAME", "INDEX_HOST");
  ```

  ```java Java {11} theme={null}
  import io.pinecone.clients.Index;
  import io.pinecone.configs.PineconeConfig;
  import io.pinecone.configs.PineconeConnection;

  public class TargetIndexByHostExample {
      public static void main(String[] args) {
          PineconeConfig config = new PineconeConfig("YOUR_API_KEY");
          config.setHost("INDEX_HOST");
          PineconeConnection connection = new PineconeConnection(config);
          // For the Java SDK, you must specify both the index host and name.
          Index index = new Index(connection, "INDEX_NAME");
      }
  }
  ```

  ```go Go {21} theme={null}
  package main

  import (
      "context"
      "fmt"
      "log"

      "github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

      idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST", Namespace: "example-namespace"})
      if err != nil {
          log.Fatalf("Failed to create IndexConnection for Host %v: %v", idx.Host, err)
      }
  }
  ```
</CodeGroup>

## Reuse connections

When you target an index for upserting or querying, the client establishes a TCP connection, which is a three-step process. To avoid going through this process on every request, and reduce average request latency, [cache and reuse the index connection object](/reference/api/authentication#initialize-a-client) whenever possible.

## Use a cloud environment

If you experience slow uploads or high query latencies, it might be because you are accessing Pinecone from your home network. To decrease latency, access Pinecone/deploy your application from a cloud environment instead, ideally from the same [cloud and region](/guides/index-data/create-an-index#cloud-regions) as your index.

## Avoid batching queries

If you're batching queries, try reducing the number of queries per call to a single query vector. You can run these [queries in parallel](/guides/search/semantic-search#parallel-queries) and expect roughly the same performance as with batching.

## Avoid including vector values when not needed

Including vector values increases response size -- especially with higher `top_k` values —- which can elevate round-trip latency. If you don't need the vector values in your response, set `include_values=false` to improve query performance. This applies to [`query`](/reference/api/latest/data-plane/query) and [`fetch`](/reference/api/latest/data-plane/fetch) operations.

<Note>
  On-demand indexes retrieve vector values from object storage, so `fetch` operations and queries with `include_values=true` may occasionally experience higher tail latency before values are cached on disk. DRN indexes cache values locally and are not affected.
</Note>

## Work with database limits

Pinecone has [rate limits](/reference/api/database-limits#rate-limits) to protect your applications and maintain infrastructure health. Rate limits vary based on pricing plan and apply to serverless indexes only.

<Note>
  Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide.
</Note>

To handle rate limits effectively:

* [Implement retry logic with exponential backoff](/guides/production/error-handling#handle-rate-limits-429).
* If you need higher limits for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). Most limits can be adjusted to accommodate your scaling needs.


# Increase search relevance
Source: https://docs.pinecone.io/guides/optimize/increase-relevance

Improve Pinecone search quality with reranking models, metadata filtering, and hybrid search that combines full-text and vector retrieval for RAG.

This page describes helpful techniques for improving search accuracy and relevance.

## Rerank results

[Reranking](/guides/search/rerank-results) is used as part of a two-stage vector retrieval process to improve the quality of results. You first query an index for a given number of relevant results, and then you send the query and results to a reranking model. The reranking model scores the results based on their semantic relevance to the query and returns a new, more accurate ranking. This approach is one of the simplest methods for improving quality in retrieval augmented generation (RAG) pipelines.

Pinecone provides [hosted reranking models](/guides/search/rerank-results#reranking-models) so it's easy to manage two-stage vector retrieval on a single platform. You can use a hosted model to rerank results as an integrated part of a query, or you can use a hosted model to rerank results as a standalone operation.

## Filter by metadata

Every [record](/guides/get-started/concepts#record) in an index must contain an ID and a dense or sparse vector, depending on the [type of index](/guides/index-data/indexing-overview#indexes). In addition, you can include metadata key-value pairs to store related information or context. When you search the index, you can then include a metadata filter to limit the search to records matching a filter expression.

For example, if an index contains records about books, you could use a metadata field to associate each record with a genre, like `"genre": "fiction"` or `"genre": "poetry"`. When you query the index, you could then use a metadata filter to limit your search to records related to a specific genre.

For more details, see [Filter by metadata](/guides/search/filter-by-metadata).

## Use full-text search for keyword matching

When relevance depends on exact keyword or phrase matches over text content — for example, product names, technical IDs, named entities, or jargon — we recommend [full-text search](/guides/search/full-text-search). It uses **BM25** ranking on `string` fields you've declared with `full_text_search` enabled and supports Lucene query syntax (`query_string`), including phrase, boolean, and proximity operators, plus the `$match_phrase` filter for exact phrase matching against text fields.

An index with a document schema can also include `dense_vector` and `sparse_vector` fields in the same schema, so you can combine BM25 token matching with semantic or sparse-vector ranking on a single index. A single search request ranks by one scoring type — restrict a `dense_vector` or `sparse_vector` search with a text-match filter (`$match_phrase`, `$match_all`, `$match_any`) on an FTS-enabled `string` field, or run BM25 and dense (or sparse) searches separately and merge the results client-side.

For more details, see [Full-text search](/guides/search/full-text-search).

## Match the query and passage embedding paths

When you use [integrated embedding](/guides/index-data/indexing-overview#integrated-embedding) with a model like [`llama-text-embed-v2`](/models/llama-text-embed-v2) or [`multilingual-e5-large`](/models/multilingual-e5-large), Pinecone embeds upserted data with the `passage` input type and embeds query text with the `query` input type. The encoder is the same, but the input type changes the resulting vector, so the *same* string embedded as a query and as a passage produces two different vectors. This is intentional in E5- and Llama-style models: the asymmetry is what makes a short query match a longer, semantically related passage.

A common consequence is that searching by text for the exact string you upserted does not return a similarity score near `1.0`. For example, querying for the exact text `"JetBlue Flights and Extras"` against a record containing that same text can score around `0.58`, while searching by the raw passage vector for the same record scores near `1.0`. The text query takes the `query` path and the stored record was embedded via the `passage` path, so the two vectors are not identical.

**Is a low score expected for identical short strings?** Yes. The query/passage split has the largest effect on short, low-semantic text such as exact names, error codes, SKUs, and IDs, where there is little meaning for the model to align across the two paths. Scores in roughly the `0.5`–`0.8` range for identical short strings are normal. The asymmetry helps on true semantic search (a short question matched to a longer answer passage) and only looks like a problem on exact-token-match workloads.

**When should you query through the passage path?** Only when the workload is exact or near-exact lookup (IDs, error logs, product names) rather than semantic search, and you want exact matches to score near `1.0`. You can override the read-time input type at the index level with [`configure_index`](/reference/api/latest/control-plane/configure_index). Set `model` and `field_map` to the index's existing values, and set `read_parameters.input_type` to `passage`:

```python Python theme={null}
from pinecone import Pinecone

pc = Pinecone(api_key="YOUR_API_KEY")

pc.configure_index(
    name="docs-example",
    embed={
        "model": "llama-text-embed-v2",
        "field_map": {"text": "chunk_text"},
        "read_parameters": {"input_type": "passage"}
    }
)
```

Note the trade-offs:

* This setting degrades true semantic search, since queries no longer use the input type the model was trained to expect.
* It applies to the whole index. With integrated inference you cannot choose `query` or `passage` per request. If you need that control, embed text yourself with the [Inference API](/reference/api/latest/inference/generate-embeddings) and search with the [`query`](/reference/api/latest/data-plane/query) operation using your own vectors.

For pure exact-match retrieval, a [sparse index](/guides/index-data/indexing-overview#indexes-with-sparse-vectors) or [full-text search](/guides/search/full-text-search) is usually a better fit than forcing dense embeddings through the passage path. See [Use full-text search for keyword matching](#use-full-text-search-for-keyword-matching) above for when keyword and phrase matching is the right tool.

## Use hybrid search

When you have both dense and sparse vectors for the same records and want to combine semantic and lexical signals at query time, you can use hybrid search. [Semantic search](/guides/search/semantic-search) can miss results based on exact keyword matches, especially in scenarios involving domain-specific terminology, while sparse-vector [lexical search](/guides/search/lexical-search) can miss results based on relationships, such as synonyms and paraphrases. Hybrid search combines the two.

There are two ways to do this:

* [Use a single index for dense and sparse vectors](/guides/search/hybrid-search#use-a-single-index-for-dense-and-sparse-vectors). This is the **recommended** approach for most use cases because you make requests to a single index, the linkage between dense and sparse vectors is implicit, and you can perform hybrid queries with a single request. Note that you'll need to [normalize sparse and dense values](/guides/search/hybrid-search#normalize-sparse-and-dense-values) at query time so the unbounded sparse component doesn't dominate the combined score.
* [Use separate indexes for dense and sparse vectors](/guides/search/hybrid-search#use-separate-indexes-for-dense-and-sparse-vectors). This approach provides more flexibility but requires managing two indexes, maintaining linkages between vectors, and querying each index separately before merging results.

If you'd rather not tune sparse and dense weights at all, an [index with a document schema](/guides/get-started/concepts#document) with a multi-field schema is a simpler single-index alternative: declare FTS-enabled `string` fields alongside a `dense_vector` or `sparse_vector` field on the same index, then either restrict the dense (or sparse) search with a text-match filter on the lexical field, or run separate searches and merge the results client-side.

For more details, including guidance on choosing the right approach, see [Hybrid search](/guides/search/hybrid-search).

## Explore chunking strategies

You can chunk your content in different ways to get better results. Consider factors like the length of the content, the complexity of queries, and how results will be used in your application.

For more details, see [Chunking strategies](https://www.pinecone.io/learn/chunking-strategies/).


# Increase throughput
Source: https://docs.pinecone.io/guides/optimize/increase-throughput

Increase Pinecone throughput with bulk import from object storage, batch upserts, parallel requests, and the Python gRPC SDK for faster ingestion.

## Import from object storage

[Importing from object storage](/guides/index-data/import-data) is the most efficient and cost-effective method to load large numbers of records into an index. You store your data as Parquet files in object storage, integrate your object storage with Pinecone, and then start an asynchronous, long-running operation that imports and indexes your records.

## Upsert in batches

[Upserting in batches](/guides/index-data/upsert-data#upsert-in-batches) is another efficient way to ingest large numbers of records (up to 1000 per batch). Batch upserting is also a good option if you cannot work around bulk import's current [limitations](/guides/index-data/import-data#import-limits).

## Upsert/search in parallel

Pinecone is thread-safe, so you can send multiple [upsert](/guides/index-data/upsert-data#upsert-in-parallel) requests and multiple [query](/guides/search/semantic-search#parallel-queries) requests in parallel to help increase throughput.

## Python SDK options

### Use gRPC

Use the [Python SDK with gRPC extras](/reference/sdks/python/overview) to run data operations such as upserts and queries over [gRPC](https://grpc.io/) rather than HTTP for a modest performance improvement.

### Upsert from a dataframe

To quickly ingest data when using the Python SDK, use the [`upsert_from_dataframe` method](/reference/sdks/python/overview#upsert-from-a-dataframe). The method includes retry logic and `batch_size`, and is performant especially with Parquet file data sets.

## See also

Read more about [high-throughput optimizations](https://www.pinecone.io/blog/working-at-scale/) on our blog.


# Save on costs
Source: https://docs.pinecone.io/guides/optimize/save-on-costs

Save on Pinecone costs by using bulk import over upsert, namespaces for multitenancy, and query patterns that reduce read unit consumption.

## Credits and discounts

In addition to the workload optimizations below, you can lower your effective rate:

* **Prepaid credits and annual commitments** earn discounted usage rates. See [Prepaid credits](/guides/manage-cost/understanding-cost#prepaid-credits).
* **One-time bulk import credit.** Standard and Enterprise organizations receive a one-time 1 TB credit for [importing data from object storage](/guides/manage-cost/understanding-cost#imports).
* **Dedicated read nodes** can lower cost for sustained, high read throughput when you fully use the provisioned capacity (see [Choose the right index capacity mode](#choose-the-right-index-capacity-mode)).
* **Volume discounts.** Standard and Enterprise customers can [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) to discuss cost optimization and discounts.

## Prefer bulk import over upsert for large loads

When you need to populate a new namespace or load a large dataset (for example, millions of records or hundreds of GB), [importing from object storage](/guides/index-data/import-data) is usually the most efficient and cost-effective path compared to streaming [upserts](/guides/index-data/upsert-data).

* **Import** is optimized for one-time or bulk loads from Parquet in your object store and is priced based on data read during the job. See [Import cost](/guides/manage-cost/understanding-cost#imports).
* **Upsert** is priced in write units based on request size; many small requests can cost more than fewer large ones for the same total data. See [Write unit pricing](/guides/manage-cost/understanding-cost#write-units).

Use upsert (including [batch upsert](/guides/index-data/upsert-data#upsert-in-batches)) for ongoing, incremental ingestion after your initial load. For how import and upsert compare, see the [data ingestion overview](/guides/index-data/data-ingestion-overview).

Partitioning tenants with [namespaces](/guides/index-data/implement-multitenancy) instead of many separate indexes often lowers storage overhead and query cost, because cost depends in part on how much data each query scans. For patterns and rationale, see [Manage cost](/guides/manage-cost/manage-cost#use-namespaces-for-multitenancy).

## Right-size reads and queries

* Avoid returning vector values in read responses when you do not need them (`include_values=false`), especially at high `top_k`. Values are typically the largest part of a response, so omitting them lowers [egress](/guides/manage-cost/understanding-cost#egress) and helps you stay within your plan's egress allowance.
* Use [metadata filters](/guides/search/filter-by-metadata) so queries scan fewer records where your workload allows.

<Note>
  Omitting values lowers egress, not [read units](/guides/manage-cost/understanding-cost#read-units): query read unit cost depends on the size of the namespace scanned, not on the size of the response.
</Note>

<Note>
  Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide.
</Note>

## Choose the right index capacity mode

For sustained, high read throughput, [dedicated read nodes](/guides/index-data/dedicated-read-nodes) can be more cost-effective than on-demand when you fully utilize provisioned read capacity. For spiky or low-QPS workloads, on-demand may be cheaper. See [When to use dedicated read nodes](/guides/index-data/dedicated-read-nodes#when-to-use-dedicated-read-nodes) and [Understanding cost](/guides/manage-cost/understanding-cost).

## See also

* [Decrease latency](/guides/optimize/decrease-latency)
* [Increase throughput](/guides/optimize/increase-throughput)
* [Manage cost](/guides/manage-cost/manage-cost)


# Access your invoices
Source: https://docs.pinecone.io/guides/organizations/manage-billing/access-your-invoices

View and download your Pinecone organization billing invoices in the console, including invoice history, receipts, and payment records.

You can access your billing history and invoices in the Pinecone console:

1. Go to [**Settings > Billing > Overview**](https://app.pinecone.io/organizations/-/settings/billing).
2. Scroll down to the **Payment history and invoices** section.
3. For each billing period, you can download the invoice by clicking the **Download** button.

Each invoice includes line items for the services used during the billing period. If the total cost of that usage is below the monthly minimum, the invoice also includes a line item covering the rest of the minimum usage commitment.


# Change your payment method
Source: https://docs.pinecone.io/guides/organizations/manage-billing/change-payment-method

Update your Pinecone organization payment method in the console, including credit card details, billing address, and payment preferences.

You can pay for the [Standard and Enterprise plans](https://www.pinecone.io/pricing/) with a credit/debit card or through the AWS Marketplace, Microsoft Marketplace, or Google Cloud Marketplace. This page describes how to switch between these payment methods.

<Note>
  To change your payment method, you must be an [organization owner or billing admin](/guides/organizations/understanding-organizations#organization-roles).
</Note>

<Note>
  The [Builder plan](https://www.pinecone.io/pricing/) is available with credit/debit card billing only and is not supported through cloud marketplaces.
</Note>

To switch a Builder-plan organization to marketplace billing, first [upgrade to the Standard or Enterprise plan](/guides/organizations/manage-billing/upgrade-billing-plan) using the marketplace subscription flow.

## Credit card → marketplace

To change from credit card to marketplace billing, you'll need to:

1. Create a new Pinecone organization through the marketplace
2. Migrate your existing projects to the new Pinecone organization
3. Add your team members to the new Pinecone organization
4. Downgrade your original Pinecone organization once migration is complete

<Tabs>
  <Tab title="Credit card → Google Cloud">
    To change from paying with a credit card to paying through the Google Cloud Marketplace, do the following:

    1. Subscribe to Pinecone in the Google Cloud Marketplace:

       1. In the Google Cloud Marketplace, go to the [Pinecone listing](https://console.cloud.google.com/marketplace/product/pinecone-public/pinecone).
       2. Click **Subscribe**.
       3. On the **Order Summary** page, select a billing account, accept the terms and conditions, and click **Subscribe**.

          <Note>The billing unit listed does not reflect the actual cost or metering of costs for Pinecone. See the [Pinecone Pricing page](https://www.pinecone.io/pricing/) for accurate details.</Note>
       4. On the **Your order request has been sent to Pinecone** modal, click **Sign up with Pinecone**. This takes you to a Google-specific Pinecone sign-up page.
       5. Sign up using the same authentication method as your existing Pinecone organization.

    2. Create a new Pinecone organization and connect it to your Google Cloud Marketplace account:

       1. On the **Connect GCP to Pinecone** page, choose **Select an organization > + Create New Organization**.

          <Note>If you see a message saying that the subscription is still in process, wait a few minutes, refresh the page, and proceed only when the message has disappeared.</Note>
       2. Enter the name of the new organization and click **Connect to Pinecone**.
       3. On the **Confirm GCP marketplace Connection** modal, click **Connect**. This takes you to your new organization in the Pinecone console.

    3. Migrate your projects to the new Pinecone organization:

       1. In the Pinecone console, go to [**Settings > Access > Members**](https://app.pinecone.io/organizations/-/settings/access/members).
       2. Make sure the **Owner** email address for your original organization is set as an **Owner** or **Billing Admin** for your new organization. This allows Pinecone to verify that both the original and new organizations are owned by the same person.
       3. Go to [**Settings > Manage**](https://app.pinecone.io/organizations/-/settings/manage) and copy your new organization ID.
       4. Go to [**Settings > Support > Tickets**](https://app.pinecone.io/organizations/-/settings/support/ticket/create).
       5. For **Ticket category**, select **Project or Organization Management**.
       6. For **Subject**, enter "Migrate projects to a new organization".
       7. For **Description**, enter the following:

          ```
          I am changing my payment method from credit card to Google Cloud Marketplace. 
          Please migrate my projects to my new organization: `<NEW_ORG_ID>`
          ```
       8. Click **Submit**.

    4. Add your team members to the new organization:

       1. In the Pinecone console, go to [**Settings > Access > Members**](https://app.pinecone.io/organizations/-/settings/access/members).
       2. [Add your team members to the new organization](/guides/organizations/manage-organization-members#add-a-member-to-an-organization).

    5. Downgrade your original Pinecone organization:

       <Note>
         Do not downgrade your original organization until you receive a confirmation that Pinecone has finished the migration to your new organization.
       </Note>

       1. In the Pinecone console, go to your original organization.
       2. Go to **Settings > Billing > Plans**.
       3. In the **Starter** section, click **Downgrade**.
       4. Click **Confirm downgrade**.

    Going forward, your usage of Pinecone will be billed through the Google Cloud Marketplace.

    <Warning>
      You can [delete your original organization](/troubleshooting/delete-your-organization). However, before deleting, make sure to [download your past invoices](/guides/organizations/manage-billing/access-your-invoices) since you will lose access to them once the organization is deleted.
    </Warning>
  </Tab>

  <Tab title="Credit card → AWS">
    To change from paying with a credit card to paying through the AWS Marketplace, do the following:

    1. Subscribe to Pinecone in the AWS Marketplace:

       1. In the AWS Marketplace, go to the [Pinecone listing](https://aws.amazon.com/marketplace/pp/prodview-xhgyscinlz4jk).
       2. Click **View purchase options**.
       3. On the **Subscribe to Pinecone Vector Database** page, review the offer and then click **Subscribe**.

          <Note>The billing unit listed does not reflect the actual cost or metering of costs for Pinecone. See the [Pinecone Pricing page](https://www.pinecone.io/pricing/) for accurate details.</Note>
       4. You'll see a message stating that your subscription is in process. Click **Set up your account**. This takes you to an AWS-specific Pinecone sign-up page.
       5. Sign up using the same authentication method as your existing Pinecone organization.

    2. Create a new Pinecone organization and connect it to your AWS account:

       1. On the **Connect AWS to Pinecone** page, choose **Select an organization > + Create New Organization**.

       <Note>If you see a message saying that the subscription is still in process, wait a few minutes, refresh the page, and proceed only when the message has disappeared.</Note>

       1. Enter the name of the new organization and click **Connect to Pinecone**.
       2. On the **Confirm AWS Marketplace Connection** modal, click **Connect**. This takes you to your new organization in the Pinecone console.

    3. Migrate your projects to the new Pinecone organization:

       1. In the Pinecone console, go to [**Settings > Access > Members**](https://app.pinecone.io/organizations/-/settings/access/members).
       2. Make sure the **Owner** email address for your original organization is set as an **Owner** or **Billing Admin** for your new organization. This allows Pinecone to verify that both the original and new organizations are owned by the same person.
       3. Go to [**Settings > Manage**](https://app.pinecone.io/organizations/-/settings/manage) and copy your new organization ID.
       4. Go to [**Settings > Support > Tickets**](https://app.pinecone.io/organizations/-/settings/support/ticket/create).
       5. For **Ticket category**, select **Project or Organization Management**.
       6. For **Subject**, enter "Migrate projects to a new organization".
       7. For **Description**, enter the following:

          ```
          I am changing my payment method from credit card to Google Cloud Marketplace. 
          Please migrate my projects to my new organization: `<NEW_ORG_ID>`
          ```
       8. Click **Submit**.

    4. Add your team members to the new organization:

       1. In the Pinecone console, go to [**Settings > Access > Members**](https://app.pinecone.io/organizations/-/settings/access/members).
       2. [Add your team members to the new organization](/guides/organizations/manage-organization-members#add-a-member-to-an-organization).

    5. Downgrade your original Pinecone organization:

       <Note>
         Do not downgrade your original organization until you receive a confirmation that Pinecone has finished the migration to your new organization.
       </Note>

       1. In the Pinecone console, go to your original organization.
       2. Go to **Settings > Billing > Plans**.
       3. In the **Starter** section, click **Downgrade**.
       4. Click **Confirm downgrade**.

    Going forward, your usage of Pinecone will be billed through the AWS Marketplace.

    <Warning>
      You can [delete your original organization](/troubleshooting/delete-your-organization). However, before deleting, make sure to [download your past invoices](/guides/organizations/manage-billing/access-your-invoices) since you will lose access to them once the organization is deleted.
    </Warning>
  </Tab>

  <Tab title="Credit card → Microsoft">
    To change from paying with a credit card to paying through the Microsoft Marketplace, do the following:

    1. Subscribe to Pinecone in the Microsoft Marketplace:

       1. In the Microsoft Marketplace, go to the [Pinecone listing](https://marketplace.microsoft.com/product/saas/pineconesystemsinc1688761585469.pineconesaas).
       2. Click **Get it now**.
       3. Select the **Pinecone - Pay As You Go** plan.
       4. Click **Subscribe**.
       5. On the **Subscribe to Pinecone** page, select the required details and click **Review + subscribe**.

          <Note>The billing unit listed does not reflect the actual cost or metering of costs for Pinecone. See the [Pinecone Pricing page](https://www.pinecone.io/pricing/) for accurate details.</Note>
       6. Click **Subscribe**.
       7. After the subscription is approved, click **Configure account now**. This redirects you to an Microsoft-specific Pinecone login page.
       8. Sign up using the same authentication method as your existing Pinecone organization.

    2. Create a new Pinecone organization and connect it to your Microsoft Marketplace account:

       1. On the **Connect Azure to Pinecone** page, choose **Select an organization > + Create New Organization**.

       <Note>If you see a message saying that the subscription is still in process, wait a few minutes, refresh the page, and proceed only when the message has disappeared.</Note>

       1. Enter the name of the new organization and click **Connect to Pinecone**.
       2. On the **Connect Azure marketplace connection** modal, click **Connect**. This takes you to your new organization in the Pinecone console.

    3. Migrate your projects to the new Pinecone organization:

       1. In the Pinecone console, go to [**Settings > Access > Members**](https://app.pinecone.io/organizations/-/settings/access/members).
       2. Make sure the **Owner** email address for your original organization is set as an **Owner** or **Billing Admin** for your new organization. This allows Pinecone to verify that both the original and new organizations are owned by the same person.
       3. Go to [**Settings > Manage**](https://app.pinecone.io/organizations/-/settings/manage) and copy your new organization ID.
       4. Go to [**Settings > Support > Tickets**](https://app.pinecone.io/organizations/-/settings/support/ticket/create).
       5. For **Ticket category**, select **Project or Organization Management**.
       6. For **Subject**, enter "Migrate projects to a new organization".
       7. For **Description**, enter the following:

          ```
          I am changing my payment method from credit card to Microsoft Marketplace. 
          Please migrate my projects to my new organization: `<NEW_ORG_ID>`
          ```
       8. Click **Submit**.

    4. Add your team members to the new organization:

       1. In the Pinecone console, go to [**Settings > Access > Members**](https://app.pinecone.io/organizations/-/settings/access/members).
       2. [Add your team members to the new organization](/guides/organizations/manage-organization-members#add-a-member-to-an-organization).

    5. Downgrade your original Pinecone organization:

       <Note>
         Do not downgrade your original organization until you receive a confirmation that Pinecone has finished the migration to your new organization.
       </Note>

       1. In the Pinecone console, go to your original organization.
       2. Go to **Settings > Billing > Plans**.
       3. In the **Starter** section, click **Downgrade**.
       4. Click **Confirm downgrade**.

    Going forward, your usage of Pinecone will be billed through the Microsoft Marketplace.

    <Warning>
      You can [delete your original organization](/troubleshooting/delete-your-organization). However, before deleting, make sure to [download your past invoices](/guides/organizations/manage-billing/access-your-invoices) since you will lose access to them once the organization is deleted.
    </Warning>
  </Tab>
</Tabs>

## Marketplace → credit card

To change from marketplace billing to credit card, you'll need to:

1. Create a new organization in your Pinecone account
2. Upgrade the new organization to the Standard or Enterprise plan
3. Migrate your existing projects to the new organization
4. Add your team members to the new organization
5. Downgrade your original organization once migration is complete

<Tabs>
  <Tab title="Google Cloud → credit card">
    To change from paying through the Google Cloud Marketplace to paying with a credit card, do the following:

    1. Create a new organization in your Pinecone account:

       1. In the Pinecone console, go to [**Organizations**](https://app.pinecone.io/organizations/-/settings/account/organizations).
       2. Click **+ Create organization**.
       3. Enter the name of the new organization and click **Create**.

    2. Upgrade the new organization:

       1. Go to [Settings > Billing > Plans](https://app.pinecone.io/organizations/-/settings/billing/plans).
       2. Click **Upgrade** in the **Standard** or **Enterprise** plan section.
       3. Click **Credit / Debit card**.
       4. Enter your credit card information.
       5. Click **Upgrade**.

       The new organization is now set up with credit card billing. You'll use this organization after completing the rest of this process.

    3. Migrate your projects to the new Pinecone organization:

       1. Go to [**Settings > Manage**](https://app.pinecone.io/organizations/-/settings/manage) and copy your new organization ID.
       2. Go to [**Settings > Support > Tickets**](https://app.pinecone.io/organizations/-/settings/support/ticket/create).
       3. For **Ticket category**, select **Project or Organization Management**.
       4. For **Subject**, enter "Migrate projects to a new organization".
       5. For **Description**, enter the following:

          ```
          I am changing my payment method from Google Cloud Marketplace to credit card. 
          Please migrate my projects to my new organization: `<NEW_ORG_ID>`
          ```
       6. Click **Submit**.

    4. Add your team members to the new organization:

       1. In the Pinecone console, go to [**Settings > Access > Members**](https://app.pinecone.io/organizations/-/settings/access/members).
       2. [Add your team members to the new organization](/guides/organizations/manage-organization-members#add-a-member-to-an-organization).

    5. Downgrade your original Pinecone organization:

       <Note>
         Do not downgrade your original organization until you receive a confirmation that Pinecone has finished the migration to your new organization.
       </Note>

       1. In the Pinecone console, go to your original organization.
       2. Go to [**Settings > Billing > Plans**](https://app.pinecone.io/organizations/-/settings/billing/plans).
       3. In the **Starter** section, click **Downgrade**.
       4. Click **Confirm downgrade**.
       5. On the **Continue your downgrade on the GCP marketplace** modal, click **Continue to marketplace**. This takes you to your orders page in Google Cloud Marketplace.
       6. [Cancel the order](https://cloud.google.com/marketplace/docs/manage-billing#saas-products) for your original organization.

          <Tip>
            If you don't see the order, check that the correct billing account is selected.
          </Tip>

    Going forward, you'll use your new organization and your usage will be billed through the credit card you provided.

    <Warning>
      You can [delete your original organization](/troubleshooting/delete-your-organization). However, before deleting, make sure to [download your past invoices](/guides/organizations/manage-billing/access-your-invoices) since you will lose access to them once the organization is deleted.
    </Warning>
  </Tab>

  <Tab title="AWS → credit card">
    To change from paying through the AWS Marketplace to paying with a credit card, do the following:

    1. Create a new organization in your Pinecone account:

       1. In the Pinecone console, go to [**Organizations**](https://app.pinecone.io/organizations/-/settings/account/organizations).
       2. Click **+ Create organization**.
       3. Enter the name of the new organization and click **Create**.

    2. Upgrade the new organization:

       1. Go to [Settings > Billing > Plans](https://app.pinecone.io/organizations/-/settings/billing/plans).
       2. Click **Upgrade** in the **Standard** or **Enterprise** plan section.
       3. Click **Credit / Debit card**.
       4. Enter your credit card information.
       5. Click **Upgrade**.

       The new organization is now set up with credit card billing. You'll use this organization after completing the rest of this process.

    3. Migrate your projects to the new Pinecone organization:

       1. Go to [**Settings > Manage**](https://app.pinecone.io/organizations/-/settings/manage) and copy your new organization ID.
       2. Go to [**Settings > Support > Tickets**](https://app.pinecone.io/organizations/-/settings/support/ticket/create).
       3. For **Ticket category**, select **Project or Organization Management**.
       4. For **Subject**, enter "Migrate projects to a new organization".
       5. For **Description**, enter the following:

          ```
          I am changing my payment method from AWS Marketplace to credit card. 
          Please migrate my projects to my new organization: `<NEW_ORG_ID>`
          ```
       6. Click **Submit**.

    4. Add your team members to the new organization:

       1. In the Pinecone console, go to [**Settings > Access > Members**](https://app.pinecone.io/organizations/-/settings/access/members).
       2. [Add your team members to the new organization](/guides/organizations/manage-organization-members#add-a-member-to-an-organization).

    5. Downgrade your original Pinecone organization:

       <Note>
         Do not downgrade your original organization until you receive a confirmation that Pinecone has finished the migration to your new organization.
       </Note>

       1. In the Pinecone console, go to your original organization.
       2. Go to [**Settings > Billing > Plans**](https://app.pinecone.io/organizations/-/settings/billing/plans).
       3. In the **Starter** section, click **Downgrade**.
       4. Click **Confirm downgrade**.
       5. On the **Continue your downgrade on the AWS marketplace** modal, click **Continue to marketplace**. This takes you to the [Manage subscriptions](https://console.aws.amazon.com/marketplace) page in the AWS Marketplace.
       6. [Cancel the subscription](https://docs.aws.amazon.com/marketplace/latest/buyerguide/cancel-subscription.html#cancel-saas-subscription) to Pinecone.

    Going forward, you'll use your new organization and your usage will be billed through the credit card you provided.

    <Warning>
      You can [delete your original organization](/troubleshooting/delete-your-organization). However, before deleting, make sure to [download your past invoices](/guides/organizations/manage-billing/access-your-invoices) since you will lose access to them once the organization is deleted.
    </Warning>
  </Tab>

  <Tab title="Microsoft → credit card">
    To change from paying through the Microsoft Marketplace to paying with a credit card, do the following:

    1. Create a new organization in your Pinecone account:

       1. In the Pinecone console, go to [**Organizations**](https://app.pinecone.io/organizations/-/settings/account/organizations).
       2. Click **+ Create organization**.
       3. Enter the name of the new organization and click **Create**.

    2. Upgrade the new organization:

       1. Go to [Settings > Billing > Plans](https://app.pinecone.io/organizations/-/settings/billing/plans).
       2. Click **Upgrade** in the **Standard** or **Enterprise** plan section.
       3. Click **Credit / Debit card**.
       4. Enter your credit card information.
       5. Click **Upgrade**.

       The new organization is now set up with credit card billing. You'll use this organization after completing the rest of this process.

    3. Migrate your projects to the new Pinecone organization:

       1. Go to [**Settings > Manage**](https://app.pinecone.io/organizations/-/settings/manage) and copy your new organization ID.
       2. Go to [**Settings > Support > Tickets**](https://app.pinecone.io/organizations/-/settings/support/ticket/create).
       3. For **Ticket category**, select **Project or Organization Management**.
       4. For **Subject**, enter "Migrate projects to a new organization".
       5. For **Description**, enter the following:

          ```
          I am changing my payment method from Microsoft Marketplace to credit card. 
          Please migrate my projects to my new organization: `<NEW_ORG_ID>`
          ```
       6. Click **Submit**.

    4. Add your team members to the new organization:

       1. In the Pinecone console, go to [**Settings > Access > Members**](https://app.pinecone.io/organizations/-/settings/access/members).
       2. [Add your team members to the new organization](/guides/organizations/manage-organization-members#add-a-member-to-an-organization).

    5. Downgrade your original Pinecone organization:

       <Note>
         Do not downgrade your original organization until you receive a confirmation that Pinecone has finished the migration to your new organization.
       </Note>

       1. In the Pinecone console, go to your original organization.
       2. Go to [**Settings > Billing > Plans**](https://app.pinecone.io/organizations/-/settings/billing/plans).
       3. In the **Starter** section, click **Downgrade**.
       4. Click **Confirm downgrade**.
       5. On the **Continue your downgrade on Azure marketplace** modal, click **Continue to marketplace**.
       6. On the **SaaS** page, click your subscription to Pinecone.
       7. Click **Cancel subscription**.
       8. Confirm the cancellation.

    Going forward, you'll use your new organization and your usage will be billed through the credit card you provided.

    <Warning>
      You can [delete your original organization](/troubleshooting/delete-your-organization). However, before deleting, make sure to [download your past invoices](/guides/organizations/manage-billing/access-your-invoices) since you will lose access to them once the organization is deleted.
    </Warning>
  </Tab>
</Tabs>

## Marketplace → marketplace

To change from one marketplace to another, you'll need to:

1. Subscribe to Pinecone in the new marketplace
2. Connect your existing org to the new marketplace
3. Cancel your subscription in the old marketplace

<Tabs>
  <Tab title="Any marketplace → Google Cloud">
    To change to a Google Cloud Marketplace billing account, do the following:

    1. Subscribe to Pinecone in the Google Cloud Marketplace:

       1. In the Google Cloud Marketplace, go to the [Pinecone listing](https://console.cloud.google.com/marketplace/product/pinecone-public/pinecone).
       2. Click **Subscribe**.
       3. On the **Order Summary** page, select a billing account, accept the terms and conditions, and click **Subscribe**.

          <Note>The billing unit listed does not reflect the actual cost or metering of costs for Pinecone. See the [Pinecone Pricing page](https://www.pinecone.io/pricing/) for accurate details.</Note>
       4. On the **Your order request has been sent to Pinecone** modal, click **Sign up with Pinecone**. This takes you to a Google-specific Pinecone login page.
       5. Log in to your Pinecone account. Use the same authentication method as your existing Pinecone organization.

    2. Connect your existing org to your Google account:

       1. On the **Connect GCP to Pinecone** page, select the Pinecone organization that you want to use Google Cloud Marketplace.

          <Note>If you see a message saying that the subscription is still in process, wait a few minutes, refresh the page, and proceed only when the message has disappeared.</Note>
       2. On the **Confirm GCP marketplace connection** modal, click **Connect**. This takes you to your organization in the Pinecone console.

          Going forward, your usage of Pinecone will be billed through the Google Cloud Marketplace.

    3. Cancel your subscription in your previous marketplace:

       * For AWS:
         1. In the AWS Marketplace, go to the [Manage subscriptions](https://console.aws.amazon.com/marketplace) page in the AWS Marketplace.
         2. [Cancel the subscription](https://docs.aws.amazon.com/marketplace/latest/buyerguide/cancel-subscription.html#cancel-saas-subscription) to Pinecone.

       * For Microsoft:
         1. Go to [Azure SaaS Resource Management](https://portal.azure.com/#blade/HubsExtension/BrowseResourceBlade/resourceType/Microsoft.SaaS%2Fresources).
         2. Select your subscription to Pinecone.
         3. Click **Cancel subscription**.
         4. Confirm the cancellation.
  </Tab>

  <Tab title="Any marketplace → AWS">
    To change to an AWS Marketplace billing account, do the following:

    1. Subscribe to Pinecone in the AWS Marketplace:

       1. In the AWS Marketplace, go to the [Pinecone listing](https://aws.amazon.com/marketplace/pp/prodview-xhgyscinlz4jk) in the AWS Marketplace.
       2. Click **View purchase options**.
       3. On the **Subscribe to Pinecone Vector Database** page, review the offer and then click **Subscribe**.

          <Note>The billing unit listed does not reflect the actual cost or metering of costs for Pinecone. See the [Pinecone Pricing page](https://www.pinecone.io/pricing/) for accurate details.</Note>
       4. You'll see a message stating that your subscription is in process. Click **Set up your account**. This takes you to an AWS-specific Pinecone login page.
       5. Log in to your Pinecone account. Use the same authentication method as your existing Pinecone organization.

    2. Connect your existing org to your AWS account:

       1. On the **Connect AWS to Pinecone** page, select the Pinecone organization that you want to change to AWS Marketplace.

          <Note>If you see a message saying that the subscription is still in process, wait a few minutes, refresh the page, and proceed only when the message has disappeared.</Note>
       2. On the **Confirm AWS marketplace connection** modal, click **Connect**. This takes you to your organization in the Pinecone console.

          Going forward, your usage of Pinecone will be billed through the AWS Marketplace.

    3. Cancel your subscription in your previous marketplace:

       * For Google Cloud Marketplace:
         1. Go to the [Orders](https://console.cloud.google.com/marketplace/orders) page.
         2. [Cancel the order](https://cloud.google.com/marketplace/docs/manage-billing#saas-products) for Pinecone.

       * For Microsoft Marketplace:
         1. Go to [Azure SaaS Resource Management](https://portal.azure.com/#blade/HubsExtension/BrowseResourceBlade/resourceType/Microsoft.SaaS%2Fresources).
         2. Select your subscription to Pinecone.
         3. Click **Cancel subscription**.
         4. Confirm the cancellation.
  </Tab>

  <Tab title="Any marketplace → Microsoft">
    To change to a Microsoft Marketplace billing account, do the following:

    1. Subscribe to Pinecone in the Microsoft Marketplace:

       1. In the Microsoft Marketplace, go to the [Pinecone listing](https://marketplace.microsoft.com/product/saas/pineconesystemsinc1688761585469.pineconesaas).
       2. Click **Get it now**.
       3. Select the **Pinecone - Pay As You Go** plan.
       4. Click **Subscribe**.
       5. On the **Subscribe to Pinecone** page, select the required details and click **Review + subscribe**.

          <Note>The billing unit listed does not reflect the actual cost or metering of costs for Pinecone. See the [Pinecone Pricing page](https://www.pinecone.io/pricing/) for accurate details.</Note>
       6. Click **Subscribe**.
       7. After the subscription is approved, click **Configure account now**. This redirects you to an Microsoft-specific Pinecone login page.
       8. Log in to your Pinecone account. Use the same authentication method as your existing Pinecone organization.

    2. Connect your existing org to your Microsoft account:

       1. On the **Connect Azure to Pinecone** page, select the Pinecone organization that you want to change to Microsoft Marketplace.

          <Note>If you see a message saying that the subscription is still in process, wait a few minutes, refresh the page, and proceed only when the message has disappeared.</Note>
       2. On the **Confirm Azure marketplace connection** modal, click **Connect**. This takes you to your organization in the Pinecone console.

          Going forward, your usage of Pinecone will be billed through the Microsoft Marketplace.

    3. Cancel your subscription in your previous marketplace:

       * For Google Cloud Marketplace:
         1. Go to the [Orders](https://console.cloud.google.com/marketplace/orders) page.
         2. [Cancel the order](https://cloud.google.com/marketplace/docs/manage-billing#saas-products) for Pinecone.

       * For AWS Marketplace:
         1. Go to the [Manage subscriptions](https://console.aws.amazon.com/marketplace) page in the AWS Marketplace.
         2. [Cancel the subscription](https://docs.aws.amazon.com/marketplace/latest/buyerguide/cancel-subscription.html#cancel-saas-subscription) to Pinecone.
  </Tab>
</Tabs>

## Credit card → credit card

To update your credit card information in the Pinecone console, do the following:

1. Go to [**Settings > Billing > Overview**](https://app.pinecone.io/organizations/-/settings/billing).
2. In the **Billing Contact** section, click **Edit**.
3. Enter your new credit card information.
4. Click **Update**.


# Downgrade your plan
Source: https://docs.pinecone.io/guides/organizations/manage-billing/downgrade-billing-plan

Downgrade your Pinecone organization from a paid plan to the free Starter plan, including plan requirements, index limits, and billing impact.

<Note>
  To change your billing plan, you must be an [organization owner or billing admin](/guides/organizations/understanding-organizations#organization-roles).
</Note>

<Tip>
  If you are on the Standard plan with credit/debit card billing and want to reduce spend without returning to the free Starter plan, consider [switching to the Builder plan](#switch-from-standard-to-builder) for a flat \$20/month.
</Tip>

## Requirements

Before you can downgrade, your organization must be under the [Starter plan quotas](/reference/api/database-limits):

* No more than 5 indexes, all serverless and in the `us-east-1` region of AWS
  * If you have serverless indexes in a region other than `us-east-1`, [create a new serverless index](/guides/index-data/create-an-index#create-a-serverless-index) in `us-east-1`, [re-upsert your data](/guides/index-data/upsert-data) into the new index, and [delete the old index](/guides/manage-data/manage-indexes#delete-an-index).
  * If you have more than 5 serverless indexes, [delete indexes](/guides/manage-data/manage-indexes#delete-an-index) until you have 5 or fewer.
  * If you have pod-based indexes, [delete them](/guides/manage-data/manage-indexes#delete-an-index).
* No more than 1 project
  * If you have more than 1 project, [delete all but 1 project](/guides/projects/manage-projects#delete-a-project).
  * Before you can delete a project, you must [delete all indexes](/guides/manage-data/manage-indexes#delete-an-index) and [delete all collections](/guides/manage-data/back-up-an-index#delete-a-collection) in the project.
* No more than 2 GB of data across all of your serverless indexes
  * If you are storing more than 2 GB of data, [delete records](/guides/manage-data/delete-data) until you're storing less than 2 GB.
* No more than 100 namespaces per serverless index
  * If any serverless index has more than 100 namespaces, [delete namespaces](/guides/manage-data/delete-data#delete-all-records-from-a-namespace) until it has 100 or fewer remaining.
* No more than 3 [assistants](/guides/assistant/overview)
  * If you have more than 3 assistants, [delete assistants](/guides/assistant/manage-assistants#delete-an-assistant) until you have 3 or fewer.
* Within the Starter plan's monthly [ingestion](/guides/assistant/pricing-and-limits#ingestion) and token limits
  * Your usage must fit within the Starter plan limits for [ingestion units](/guides/assistant/pricing-and-limits#ingestion), chat tokens, context tokens, and storage. Reduce files or usage until you are within those limits.
* No more than 1 GB of assistant storage
  * If you have more than 1 GB of assistant storage, [delete files](https://docs.pinecone.io/guides/assistant/manage-files#delete-a-file) until you're storing less than 1 GB.
* No more than 2 users
* No collections or backups (these are automatically deleted as part of the downgrade process)

<Note>
  You do not need to bring [Assistant usage](/guides/assistant/pricing-and-limits) (ingestion, tokens, and so on) under Starter caps before downgrading. If you exceed Starter limits after downgrading, new requests may be blocked until usage is within limits.
</Note>

<Note>
  **Switching from Standard to Builder instead of Starter?** Your organization must be under the [Builder plan quotas](/reference/api/database-limits), backups must be deleted, and any features not available on Builder—such as bulk import, pod-based indexes, storage integrations, RBAC, and SSO—must be removed or stopped.
</Note>

## Downgrade to the Starter plan

The downgrade process is different depending on how you are paying for Pinecone.

<Warning>
  It is important to start the downgrade process in the Pinecone console, as described below. When you do so, Pinecone checks that you are under the [Starter plan quotas](#requirements) before allowing you to downgrade. In contrast, if you start the downgrade process in one of the cloud marketplaces, Pinecone cannot check that you are under these quotas before allowing you to downgrade. If you are over the quotas, Pinecone will deactivate your account, and you will need to [contact support](https://www.pinecone.io/contact/support/).
</Warning>

<Tabs>
  <Tab title="Credit card">
    If you are paying with a credit card, downgrade as follows:

    1. In the Pinecone console, go to [**Settings > Billing > Plans**](https://app.pinecone.io/organizations/-/settings/billing/plans).
    2. Click **Downgrade** in the **Starter** plan section.

    Your billing will end immediately. However, you will receive a final invoice for any charges accrued in the current month.
  </Tab>

  <Tab title="Google Cloud Marketplace">
    If you are paying through the Google Cloud Marketplace, downgrade as follows:

    1. In the Pinecone console, go to [**Settings > Billing > Plans**](https://app.pinecone.io/organizations/-/settings/billing/plans).
    2. In the **Starter** section, click **Downgrade**.
    3. Click **Confirm downgrade**.
    4. On the **Continue your downgrade on the GCP marketplace** modal, click **Continue to marketplace**. This takes you to your orders page in Google Cloud Marketplace.
    5. [Cancel the order](https://cloud.google.com/marketplace/docs/manage-billing#saas-products) for your Pinecone subscription.

       <Tip>
         If you don't see the order, check that the correct billing account is selected.
       </Tip>

    Your billing will end immediately. However, you will receive a final invoice for any charges accrued in the current month.
  </Tab>

  <Tab title="AWS Marketplace">
    If you are paying through the AWS Marketplace, downgrade as follows:

    1. In the Pinecone console, go to [**Settings > Billing > Plans**](https://app.pinecone.io/organizations/-/settings/billing/plans).
    2. In the **Starter** section, click **Downgrade**.
    3. Click **Confirm downgrade**.
    4. On the **Continue your downgrade on the AWS marketplace** modal, click **Continue to marketplace**. This takes you to the [Manage subscriptions](https://console.aws.amazon.com/marketplace) page in the AWS Marketplace.
    5. [Cancel the subscription](https://docs.aws.amazon.com/marketplace/latest/buyerguide/cancel-subscription.html#cancel-saas-subscription) to Pinecone.

    Your billing will end immediately. However, you will receive a final invoice for any charges accrued in the current month.
  </Tab>

  <Tab title="Microsoft Marketplace">
    If you are paying through the Microsoft Marketplace, downgrade as follows:

    1. In the Pinecone console, go to [**Settings > Billing > Plans**](https://app.pinecone.io/organizations/-/settings/billing/plans).
    2. In the **Starter** section, click **Downgrade**.
    3. Click **Confirm downgrade**.
    4. On the **Continue your downgrade on Microsoft marketplace** modal, click **Continue to marketplace**.
    5. On the **SaaS** page, click your subscription to Pinecone.
    6. Click **Cancel subscription**.
    7. Confirm the cancellation.

    Your billing will end immediately. However, you will receive a final invoice for any charges accrued in the current month.
  </Tab>
</Tabs>

## Switch from Standard to Builder

If you are on the **Standard plan** with credit/debit card billing and would like to switch to the [Builder plan](/reference/api/database-limits) (flat \$20/month), do the following:

1. Bring your organization under the [Builder plan quotas](/reference/api/database-limits). In particular, you must be within the Builder plan limits for projects, indexes, namespaces, storage, users, and monthly usage units.
2. In the Pinecone console, go to [**Settings > Billing > Plans**](https://app.pinecone.io/organizations/-/settings/billing/plans).
3. Click **Switch to Builder** in the **Builder** plan section.
4. Confirm the change.

After switching, overages are no longer billed—requests that exceed Builder quotas are blocked instead. If you need more capacity, [upgrade back to Standard or Enterprise](/guides/organizations/manage-billing/upgrade-billing-plan) at any time.

<Note>
  The [Builder plan](https://www.pinecone.io/pricing/) is available with credit/debit card billing only and is not supported through cloud marketplaces.
</Note>

If you pay through a cloud marketplace, you cannot switch to the Builder plan at this time. [Contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) to be notified when this migration becomes available.


# Download a usage report
Source: https://docs.pinecone.io/guides/organizations/manage-billing/download-usage-report

Download detailed Pinecone usage and cost reports from the console, including index consumption, storage metrics, and per-project spend breakdowns.

<Note>
  To view usage and costs across your Pinecone organization, you must be an [organization owner or billing admin](/guides/organizations/understanding-organizations#organization-roles). Also, this feature is available only to organizations on the Standard or Enterprise plans.
</Note>

The **Usage** dashboard in the Pinecone console gives you a detailed report of usage and costs across your organization, broken down by each billable SKU or aggregated by project or service. You can view the report in the console or download it as a CSV file for more detailed analysis.

1. Go to [**Settings > Usage**](https://app.pinecone.io/organizations/-/settings/usage) in the Pinecone console.
2. Select the time range to report on. This defaults to the last 30 days.
3. Select the scope for your report:
   * **SKU:** The usage and cost for each billable SKU, for example, read units per cloud region, storage size per cloud region, or tokens per embedding model.
   * **Project:** The aggregated cost for each project in your organization.
   * **Service:** The aggregated cost for each service your organization uses, for example, database (includes serverless back up and restore), assistants, inference (embedding and reranking), and collections.
4. Choose the specific SKUs, projects, or services you want to report on. This defaults to all.
5. To download the report as a CSV file, click **Download**.

   <Tip>
     The CSV download provides more granular detail than the console view, including breakdowns by individual index as well as project and index tags.
   </Tip>

Dates are shown in UTC to match billing invoices. Cost data is delayed up to three days from the actual usage date.


# Account deactivation for non-payment
Source: https://docs.pinecone.io/guides/organizations/manage-billing/non-payment-account-deactivation

Learn what happens when a Pinecone account is deactivated for non-payment: 30-day data retention, permanent deletion, and how to reactivate.

If your organization has continued non-payment on a paid billing plan, Pinecone may deactivate your account. While your account is deactivated, you cannot use Pinecone services, but your data is retained for a limited time so you can reactivate and recover it.

## Data retention after deactivation

When your account is deactivated for non-payment:

* Your account data is retained for **30 days** from deactivation.
* After 30 days, all account data is **permanently deleted**. This action cannot be undone.

<Note>
  This 30-day retention period applies specifically to accounts deactivated for continued non-payment. Other deletion flows, such as when you [delete resources](/guides/production/data-deletion) or [end your relationship with Pinecone](/guides/production/data-deletion), follow different retention timelines described in the [data deletion policy](/guides/production/data-deletion).
</Note>

If you see a deactivation notice in the Pinecone console, it reflects this policy:

> Your account has been deactivated due to continued non-payment. Account data will be retained for 30 days. After 30 days, all data will be permanently deleted. This action cannot be undone.
>
> To reactivate your account and preserve your data, please visit the billing page and update your payment information. If you believe this is an error, please reach out to our support team.

## Reactivate your account

To reactivate your account and preserve your data before the 30-day retention period ends:

1. Sign in to the [Pinecone console](https://app.pinecone.io).
2. Go to [**Settings > Billing**](https://app.pinecone.io/organizations/-/settings/billing).
3. Update your payment information or resolve the outstanding balance.

Organization [owners and billing admins](/guides/organizations/understanding-organizations#organization-roles) can update billing details. For help changing how you pay, see [Change your payment method](/guides/organizations/manage-billing/change-payment-method).

## API access while deactivated

API requests may fail with a [**402 - Payment Required**](/reference/api/errors#402---payment-required) response while your account has a payment issue or is deactivated for non-payment. After you reactivate your account, retry your requests. For general error-handling guidance, see [Error handling](/guides/production/error-handling).

## Contact support

If you believe your account was deactivated in error, [contact Support](https://www.pinecone.io/contact/support/) or [open a support ticket](https://app.pinecone.io/organizations/-/settings/support/ticket) from the console.

## See also

* [Change your payment method](/guides/organizations/manage-billing/change-payment-method)
* [Data deletion on Pinecone](/guides/production/data-deletion)
* [Billing disputes and refunds](/troubleshooting/billing-disputes-and-refunds)


# Standard trial
Source: https://docs.pinecone.io/guides/organizations/manage-billing/standard-trial

Get $300 in credits over 21 days with the Pinecone Standard plan trial, including RBAC, bulk import, backup and restore, and higher scale limits.

The Standard trial lets you evaluate Pinecone without requiring any up-front payment. You get \$300 in credits over 21 days with access to Standard plan [features](https://www.pinecone.io/pricing/) and [limits](/reference/api/database-limits) that are suitable for testing Pinecone at scale.

<Note>
  If you're building a small or personal project, consider the free [Starter plan](https://www.pinecone.io/pricing/) or the flat-rate [Builder plan](https://www.pinecone.io/pricing/) instead.
</Note>

## Key features

* \$300 in credits
* 21 days of access to Standard plan [features](https://www.pinecone.io/pricing/), including:
  * [Bulk import](/guides/index-data/import-data)
  * [Backup and restore](/guides/manage-data/backups-overview)
  * [RBAC (role-based access control)](/guides/production/security-overview#role-based-access-controls-rbac)
* [Higher limits](/reference/api/database-limits) for testing at scale
* Access to all [cloud regions](/guides/index-data/create-an-index#cloud-regions)
* Access to [Developer Support](https://www.pinecone.io/pricing/?plans=support)

## Expiration

At the end of a Standard trial, or when you've used all of your credits, you can take one of the following actions:

* Add a payment method and continue on with the Standard plan.
* Upgrade to the Enterprise plan.
* [Downgrade to the Starter plan](#downgrading-to-the-starter-plan) (you can also do this before your trial expires, if you choose).

<Note>
  Learn more about [pricing](https://www.pinecone.io/pricing/).
</Note>

## Downgrading to the Starter plan

To downgrade from a Standard trial to the Starter plan, you'll need to bring your usage within Starter plan limits.

* No more than 5 indexes, all serverless and in the `us-east-1` region of AWS
  * If you have serverless indexes in a region other than `us-east-1`, [create a new serverless index](/guides/index-data/create-an-index#create-a-serverless-index) in `us-east-1`, [re-upsert your data](/guides/index-data/upsert-data) into the new index, and [delete the old index](/guides/manage-data/manage-indexes#delete-an-index).
  * If you have more than 5 serverless indexes, [delete indexes](/guides/manage-data/manage-indexes#delete-an-index) until you have 5 or fewer.
  * If you have pod-based indexes, [delete them](/guides/manage-data/manage-indexes#delete-an-index).
* No more than 1 project
  * If you have more than 1 project, [delete all but 1 project](/guides/projects/manage-projects#delete-a-project).
  * Before you can delete a project, you must [delete all indexes](/guides/manage-data/manage-indexes#delete-an-index) and [delete all collections](/guides/manage-data/back-up-an-index#delete-a-collection) in the project.
* No more than 2 GB of data across all of your serverless indexes
  * If you are storing more than 2 GB of data, [delete records](/guides/manage-data/delete-data) until you're storing less than 2 GB.
* No more than 100 namespaces per serverless index
  * If any serverless index has more than 100 namespaces, [delete namespaces](/guides/manage-data/delete-data#delete-all-records-from-a-namespace) until it has 100 or fewer remaining.
* No more than 3 [assistants](/guides/assistant/overview)
  * If you have more than 3 assistants, [delete assistants](/guides/assistant/manage-assistants#delete-an-assistant) until you have 3 or fewer.
* Within the Starter plan's monthly [ingestion](/guides/assistant/pricing-and-limits#ingestion) and token limits
  * Your usage must fit within the Starter plan limits for [ingestion units](/guides/assistant/pricing-and-limits#ingestion), chat tokens, context tokens, and storage. Reduce files or usage until you are within those limits.
* No more than 1 GB of assistant storage
  * If you have more than 1 GB of assistant storage, [delete files](https://docs.pinecone.io/guides/assistant/manage-files#delete-a-file) until you're storing less than 1 GB.
* No more than 2 users
* No collections or backups (these are automatically deleted as part of the downgrade process)

<Note>
  You do not need to bring [Assistant usage](/guides/assistant/pricing-and-limits) (ingestion, tokens, and so on) under Starter caps before downgrading. If you exceed Starter limits after downgrading, new requests may be blocked until usage is within limits.
</Note>

<Note>
  **Switching from Standard to Builder instead of Starter?** Your organization must be under the [Builder plan quotas](/reference/api/database-limits), backups must be deleted, and any features not available on Builder—such as bulk import, pod-based indexes, storage integrations, RBAC, and SSO—must be removed or stopped.
</Note>

If you have questions, [contact Support](https://www.pinecone.io/contact/support/).

## Limits

* Each organization is allowed only one trial.
* Organizations already on a Builder, Standard, or Enterprise plan cannot activate a Standard plan trial.
* Organizations that initially subscribed to Pinecone through marketplace partners cannot activate a Standard plan trial.

If you have any questions, [contact Support](https://www.pinecone.io/contact/support/).


# Upgrade your plan
Source: https://docs.pinecone.io/guides/organizations/manage-billing/upgrade-billing-plan

Upgrade to a paid Pinecone plan for higher limits, backups, private endpoints, audit logs, and access to the Builder, Standard, or Enterprise tiers.

This page describes how to upgrade from the free Starter plan to the [Builder, Standard, or Enterprise plan](https://www.pinecone.io/pricing/), paying either with a credit/debit card or through a supported cloud marketplace.

<Note>
  To change your plan, you must be an [organization owner or billing admin](/guides/organizations/understanding-organizations#organization-roles).
</Note>

<Tip>
  To commit to annual spending, [contact Pinecone](https://www.pinecone.io/contact).
</Tip>

## Upgrade to the Builder plan

The Builder plan is a flat \$20/month plan with higher quotas than Starter and no usage overages. To upgrade from Starter to Builder:

1. In the Pinecone console, go to [Settings > Billing > Plans](https://app.pinecone.io/organizations/-/settings/billing/plans).
2. Click **Upgrade** in the **Builder** plan section.
3. Enter your credit/debit card information.
4. Click **Upgrade**.

After upgrading, your organization is immediately on the Builder plan with the higher [Builder plan quotas](/reference/api/database-limits). If you need additional capacity or features not included in Builder, you can [upgrade to Standard or Enterprise](#upgrade-to-the-standard-or-enterprise-plan) at any time.

<Note>
  The [Builder plan](https://www.pinecone.io/pricing/) is available with credit/debit card billing only and is not supported through cloud marketplaces.
</Note>

## Upgrade to the Standard or Enterprise plan

### Pay with a credit/debit card

To upgrade your plan to Standard or Enterprise and pay with a credit/debit card, do the following:

1. In the Pinecone console, go to [Settings > Billing > Plans](https://app.pinecone.io/organizations/-/settings/billing/plans).
2. Click **Upgrade** in the **Standard** or **Enterprise** plan section.
3. Click **Credit / Debit card**.
4. Enter your credit card information.
5. Click **Upgrade**.

After upgrading, you will immediately start paying for usage of your Pinecone indexes, including the serverless indexes that were free on the Starter plan. For more details about how costs are calculated, see [Understanding cost](/guides/manage-cost/understanding-cost).

### Pay through the Google Cloud Marketplace

To upgrade your plan to Standard or Enterprise and pay through the Google Cloud Marketplace, do the following:

1. In the Pinecone console, go to [Settings > Billing > Plans](https://app.pinecone.io/organizations/-/settings/billing/plans).
2. Click **Upgrade** in the **Standard** or **Enterprise** plan section.
3. Click **Billing through GCP**. This takes you to the [Pinecone listing](https://console.cloud.google.com/marketplace/product/pinecone-public/pinecone) in the Google Cloud Marketplace.
4. Click **Subscribe**.
5. On the **Order Summary** page, select a billing account, accept the terms and conditions, and click **Subscribe**.

   <Note>The billing unit listed does not reflect the actual cost or metering of costs for Pinecone. See the [Pinecone Pricing page](https://www.pinecone.io/pricing/) for accurate details.</Note>
6. On the **Your order request has been sent to Pinecone** modal, click **Sign up with Pinecone**. This takes you to a Google-specific Pinecone login page.
7. Log in to your Pinecone account. Use the same authentication method as your existing Pinecone organization.
8. Select an organization from the list. You can only connect to organizations that are on the [Starter plan](https://www.pinecone.io/pricing/). Alternatively, you can opt to create a new organization.
9. Click **Connect to Pinecone** and follow the prompts.

Once your organization is connected and upgraded, you will receive a confirmation message. You will then immediately start paying for usage of your Pinecone indexes, including the serverless indexes that were free on the Starter plan. For more details about how costs are calculated, see [Understanding cost](/guides/manage-cost/understanding-cost).

### Pay through the AWS Marketplace

To upgrade your plan to Standard or Enterprise and pay through the AWS Marketplace, do the following:

1. In the Pinecone console, go to [Settings > Billing > Plans](https://app.pinecone.io/organizations/-/settings/billing/plans).
2. Click **Upgrade** in the **Standard** or **Enterprise** plan section.
3. Click **Billing through AWS**. This takes you to the [Pinecone listing](https://aws.amazon.com/marketplace/pp/prodview-xhgyscinlz4jk) in the AWS Marketplace.
4. Click **View purchase options**.
5. On the **Subscribe to Pinecone Vector Database** page, review the offer and then click **Subscribe**.

   <Note>The billing unit listed does not reflect the actual cost or metering of costs for Pinecone. See the [Pinecone Pricing page](https://www.pinecone.io/pricing/) for accurate details.</Note>
6. You'll see a message stating that your subscription is in process. Click **Set up your account**. This takes you to an AWS-specific Pinecone login page.

   <Warning>
     If the [Pinecone subscription page](https://aws.amazon.com/marketplace/saas/ordering?productId=738798c3-eeca-494a-a2a9-161bee9450b2) shows a message stating, “You are currently subscribed to this offer,” contact your team members to request an invitation to the existing AWS-linked organization. The **Set up your account** button is clickable, but Pinecone does not create a new AWS-linked organization.
   </Warning>
7. Log in to your Pinecone account. Use the same authentication method as your existing Pinecone organization.
8. Select an organization from the list. You can only connect to organizations that are on the [Starter plan](https://www.pinecone.io/pricing/). Alternatively, you can opt to create a new organization.
9. Click **Connect to Pinecone** and follow the prompts.

Once your organization is connected and upgraded, you will receive a confirmation message. You will then immediately start paying for usage of your Pinecone indexes, including the serverless indexes that were free on the Starter plan. For more details about how costs are calculated, see [Understanding cost](/guides/manage-cost/understanding-cost).

### Pay through the Microsoft Marketplace

To upgrade your plan to Standard or Enterprise and pay through the Microsoft Marketplace, do the following:

1. In the Pinecone console, go to [Settings > Billing > Plans](https://app.pinecone.io/organizations/-/settings/billing/plans).
2. Click **Upgrade** in the **Standard** or **Enterprise** plan section.
3. Click **Billing through Azure**. This takes you to the [Pinecone listing](https://marketplace.microsoft.com/product/saas/pineconesystemsinc1688761585469.pineconesaas) in the Microsoft Marketplace.
4. Click **Get it now**.
5. Select the **Pinecone - Pay As You Go** plan.
6. Click **Subscribe**.
7. On the **Subscribe to Pinecone** page, select the required details and click **Review + subscribe**.

   <Note>The billing unit listed does not reflect the actual cost or metering of costs for Pinecone. See the [Pinecone Pricing page](https://www.pinecone.io/pricing/) for accurate details.</Note>
8. Click **Subscribe**.
9. After the subscription is approved, click **Configure account now**. This redirects you to an Microsoft-specific Pinecone login page.
10. Log in to your Pinecone account. Use the same authentication method as your existing Pinecone organization.
11. Select an organization from the list. You can only connect to organizations that are on the [Starter plan](https://www.pinecone.io/pricing/). Alternatively, you can opt to create a new organization.
12. Click **Connect to Pinecone** and follow the prompts.

Once your organization is connected and upgraded, you will receive a confirmation message. You will then immediately start paying for usage of your Pinecone indexes, including the serverless indexes that were free on the Starter plan. For more details about how costs are calculated, see [Understanding cost](/guides/manage-cost/understanding-cost).


# Manage organization members
Source: https://docs.pinecone.io/guides/organizations/manage-organization-members

Add, invite, and manage members in your Pinecone organization, including assigning organization roles, changing permissions, and removing users.

This page shows how [organization owners](/guides/organizations/understanding-organizations#organization-roles) can add and manage organization members.

To assign and manage roles programmatically with the Admin API, or to manage roles for service accounts and API keys, see [Manage roles and access](/guides/production/manage-rbac).

<Tip>
  For information about managing members at the **project-level**, see [Manage project members](/guides/projects/manage-project-members).
</Tip>

## Add a member to an organization

You can add members to your organization in the [Pinecone console](https://app.pinecone.io):

1. Go to [**Settings > Access > Members**](https://app.pinecone.io/organizations/-/settings/access/members).
2. In the **Invite by email** field, enter the member's email address.
3. Choose an [**Organization role**](/guides/organizations/understanding-organizations#organization-roles) for the member. The role determines the member's permissions within Pinecone.
4. Click **Invite**.

When you invite a member to join your organization, Pinecone sends them an email containing a link that enables them to gain access to the organization or project. If they already have a Pinecone account, they still receive an email, but they can also immediately view the project.

## Change a member's role

You can change a member's role in the [Pinecone console](https://app.pinecone.io):

1. Go to [**Settings > Access > Members**](https://app.pinecone.io/organizations/-/settings/access/members).
2. In the row of the member whose role you want to change, click **ellipsis (...) menu > Edit role**.
3. Select an [**Organization role**](/guides/organizations/understanding-organizations#organization-roles) for the member.
4. Click **Edit role**.

## Remove a member

You can remove a member from your organization in the [Pinecone console](https://app.pinecone.io):

1. Go to [**Settings > Access > Members**](https://app.pinecone.io/organizations/-/settings/access/members).
2. In the row of the member you want to remove, click **ellipsis (...) menu > Remove member**.
3. Click **Remove Member**.

<Note>
  To remove yourself from an organization, click the **Leave organization** button in your user's row and confirm.
</Note>


# Manage service accounts at the organization-level
Source: https://docs.pinecone.io/guides/organizations/manage-service-accounts

Create and manage service accounts at the organization level in Pinecone for programmatic Admin API access, including client secrets and role assignment.

<Note>
  This feature is in [public preview](/release-notes/feature-availability) and available only on [Enterprise plans](https://www.pinecone.io/pricing/).
</Note>

This page shows how [organization owners](/guides/organizations/understanding-organizations#organization-roles) can add and manage service accounts at the organization-level. Service accounts enable programmatic access to Pinecone's Admin API, which can be used to create and manage projects and API keys.

<Tip>
  Once a service account is added at the organization-level, it can be added to a project. For more information, see [Manage service accounts at the project-level](/guides/projects/manage-service-accounts).
</Tip>

## Create a service account

You can create a service account in the [Pinecone console](https://app.pinecone.io):

1. Go to [**Settings > Access > Service accounts**](https://app.pinecone.io/organizations/-/settings/access/service-accounts).

2. Enter a **Name** for the service account.

3. Choose an [**Organization role**](/guides/organizations/understanding-organizations#organization-roles) for the service account. The role determines the service account's permissions within Pinecone.

4. Click **Create**.

5. Copy and save the **Client secret** in a secure place for future use. You will need the client secret to retrieve an access token.

   <Warning>
     You will not be able to see the client secret again after you close the dialog.
   </Warning>

6. Click **Close**.

Once you have created a service account, [add it to a project](/guides/projects/manage-service-accounts#add-a-service-account-to-a-project) to allow it access to the project's resources.

## Retrieve an access token

To access the Admin API, you must provide an access token to authenticate. Retrieve the access token using the client secret of a service account, which was [provided at time of creation](#create-a-service-account).

You can retrieve an access token for a service account from the `https://login.pinecone.io/oauth/token` endpoint, as shown in the following example:

```bash curl theme={null}
curl "https://login.pinecone.io/oauth/token" \ # Note: Base URL is login.pinecone.io
	-H "X-Pinecone-Api-Version: 2025-10" \
	-H "Content-Type: application/json" \
	-d '{
		"grant_type": "client_credentials",
		"client_id": "YOUR_CLIENT_ID",
		"client_secret": "YOUR_CLIENT_SECRET",
		"audience": "https://api.pinecone.io/"
	}'
```

The response will include an `access_token` field, which you can use to authenticate with the Admin API.

```
{
    "access_token":"YOUR_ACCESS_TOKEN",
    "expires_in":86400,
    "token_type":"Bearer"
}
```

## Change a service account's role

You can change a service account's role in the [Pinecone console](https://app.pinecone.io):

1. Go to [**Settings > Access > Service accounts**](https://app.pinecone.io/organizations/-/settings/access/service-accounts).
2. In the row of the service account you want to update, click **ellipsis (...) menu > Manage**.
3. Select an [**Organization role**](/guides/organizations/understanding-organizations#organization-roles) for the service account.
4. Click **Update**.

## Update service account name

You can change a service account's name in the [Pinecone console](https://app.pinecone.io):

1. Go to [**Settings > Access > Service accounts**](https://app.pinecone.io/organizations/-/settings/access/service-accounts).
2. In the row of the service account you want to update, click **ellipsis (...) menu > Manage**.
3. Enter a new **Service account name**.
4. Click **Update**.

## Rotate a service account's secret

You can rotate a service account's client secret in the [Pinecone console](https://app.pinecone.io):

1. Go to [**Settings > Access > Service accounts**](https://app.pinecone.io/organizations/-/settings/access/service-accounts).

2. In the row of the service account you want to update, click **ellipsis (...) menu > Rotate secret**.

3. **Enter the service account name** to confirm.

4. Click **Rotate client secret**.

5. Copy and save the **Client secret** in a secure place for future use.

   <Warning>
     You will not be able to see the client secret again after you close the dialog.
   </Warning>

6. Click **Close**.

## Delete a service account

Deleting a service account will remove it from all projects and will disrupt any applications using it to access Pinecone. You delete a service account in the [Pinecone console](https://app.pinecone.io):

1. Go to [**Settings > Access > Service accounts**](https://app.pinecone.io/organizations/-/settings/access/service-accounts).
2. In the row of the service account you want to update, click **ellipsis (...) menu > Delete**.
3. **Enter the service account name** to confirm.
4. Click **Delete service account**.


# Understanding organizations
Source: https://docs.pinecone.io/guides/organizations/understanding-organizations

Learn how Pinecone organizations group projects, share billing, and use organization roles to control member permissions and access to resources.

A Pinecone organization is a set of [projects](/guides/projects/understanding-projects) that use the same billing. Organizations allow one or more users to control billing and project permissions for all of the projects belonging to the organization. Each project belongs to an organization.

<Note>
  While an email address can be associated with multiple organizations, it cannot be used to create more than one organization. For information about managing organization members, see [Manage organization members](/guides/organizations/manage-organization-members).
</Note>

## Projects in an organization

Each organization contains one or more projects that share the same organization owners and billing settings. Each project belongs to exactly one organization. If you need to move a project from one organization to another, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

## Billing settings

All of the projects in an organization share the same billing method and settings. The billing settings for the organization are controlled by the organization owners.

Organization owners can update the billing contact information, update the payment method, and view and download invoices using the [Pinecone console](https://app.pinecone.io/organizations/-/settings/billing).

## Organization roles

Organization owners can manage access to their organizations and projects by assigning roles to organization members and service accounts. A role determines the permissions that a [principal](/guides/production/security-overview#role-based-access-controls-rbac) (a user, service account, or API key) has within Pinecone. The organization roles are as follows:

* **Organization owner** (`OrgOwner`): Full control over the organization, including billing, members, service accounts, security, and every project. Inherits [owner access](/guides/projects/understanding-projects#project-roles) to all projects in the organization.

* **Organization manager** (`OrgManager`): Can view organization details and create projects. Organization managers cannot manage billing, members, service accounts, or organization settings.

* **Organization member** (`OrgMember`): Can view organization details and access the projects they are added to. Organization members cannot create projects or manage organization settings. To grant project access, add the member to one or more projects and assign a [project role](/guides/projects/understanding-projects#project-roles); see [Manage project members](/guides/projects/manage-project-members).

* **Billing admin** (`OrgBillingAdmin`): Can view organization details and manage billing, subscriptions, and usage. Billing admins cannot manage members or organization settings, and they cannot manage projects unless they are also [project owners](/guides/projects/understanding-projects#project-roles).

The following table summarizes the permissions for each organization role:

| Permission                             | Owner | Manager | Member | Billing admin |
| -------------------------------------- | :---: | :-----: | :----: | :-----------: |
| View account details                   |   ✓   |    ✓    |    ✓   |       ✓       |
| Create projects                        |   ✓   |    ✓    |        |               |
| View billing and usage details         |   ✓   |         |        |       ✓       |
| Manage billing details                 |   ✓   |         |        |       ✓       |
| Invite and remove organization members |   ✓   |         |        |               |
| Update organization member roles       |   ✓   |         |        |               |
| Manage service accounts                |   ✓   |         |        |               |
| Configure single sign-on (SSO)         |   ✓   |         |        |               |
| Configure audit logs                   |   ✓   |         |        |               |
| Update organization name               |   ✓   |         |        |               |
| Delete the organization                |   ✓   |         |        |               |

## Organization single sign-on (SSO)

SSO allows organizations to manage their teams' access to Pinecone through their identity management solution. Once your integration is configured, you can specify a default role for teammates when they sign up.

<Note>For organizations that use SSO for authentication, console sessions are re-authenticated at least every 24 hours.</Note>

For more information, see [Configure single sign-on](/guides/production/configure-single-sign-on/okta).

<Note>SSO is available on Standard and Enterprise plans.</Note>

## Service accounts

<Note>
  This feature is in [public preview](/release-notes/feature-availability) and available only on [Enterprise plans](https://www.pinecone.io/pricing/).
</Note>

[Service accounts](/guides/organizations/manage-service-accounts) enable programmatic access to Pinecone's Admin API, which can be used to create and manage projects and API keys.

Use service accounts to automate infrastructure management and integrate Pinecone into your deployment workflows, rather than through manual actions in the Pinecone console. Service accounts use the [organization roles](/guides/organizations/understanding-organizations#organization-roles) and [project role](/guides/projects/understanding-projects#project-roles) for permissioning, and provide a secure and auditable way to handle programmatic access.

## See also

* [Manage organization members](/guides/organizations/manage-organization-members)
* [Manage project members](/guides/projects/manage-project-members)


# CI/CD with Pinecone Local and GitHub Actions
Source: https://docs.pinecone.io/guides/production/automated-testing

Build a GitHub Actions CI/CD workflow with Pinecone Local to run automated integration tests against an in-memory emulator without touching production.

Pinecone Local is an in-memory Pinecone Database emulator available as a Docker image.

This page shows you how to build a CI/CD workflow with Pinecone Local and [GitHub Actions](https://docs.github.com/en/actions) to test your integration without connecting to your Pinecone account, affecting production data, or incurring any usage or storage fees.

<Warning>
  Pinecone Local is not suitable for production. See [Limitations](#limitations) for details.
</Warning>

## Limitations

Pinecone Local has the following limitations:

* Pinecone Local uses the `2025-01` API version, which is not the latest stable version.
* Pinecone Local is available in Docker only.
* Pinecone Local is an in-memory emulator and is not suitable for production. Records loaded into Pinecone Local do not persist after it is stopped.
* Pinecone Local does not authenticate client requests. API keys are ignored.
* Max number of records per index: 100,000.

Pinecone Local does not currently support the following features:

* [Import from object storage](/guides/index-data/import-data)
* [Backup/restore of serverless indexes](/guides/manage-data/backups-overview)
* [Collections for pod-based indexes](/guides/indexes/pods/understanding-collections)
* [Namespace management](/guides/manage-data/manage-namespaces)
* [Pinecone Inference](/reference/api/introduction#inference)
* [Pinecone Assistant](/guides/assistant/overview)

## 1. Write your tests

Running code against Pinecone Local is just like running code against your Pinecone account, with the following differences:

* Pinecone Local does not authenticate client requests. API keys are ignored.

* The latest version of Pinecone Local uses [Pinecone API version](/reference/api/versioning) `2025-01` and requires [Python SDK](/reference/sdks/python/overview) `v6.x` or later, [Node.js SDK](/reference/sdks/node/overview) `v5.x` or later, [Java SDK](/reference/sdks/java/overview) `v4.x` or later, and [Go SDK](/reference/sdks/go/overview) `v3.x` or later.

<Note>
  Be sure to review the [limitations](#limitations) of Pinecone Local before using it for development or testing.
</Note>

**Example**

The following example assumes that you have [started Pinecone Local without indexes](/guides/operations/local-development#database-emulator). It initializes a client, creates [an index for dense vectors](/guides/index-data/indexing-overview#indexes-with-dense-vectors) and [an index for sparse vectors](/guides/index-data/indexing-overview#indexes-with-sparse-vectors), upserts records into each, checks their record counts, and queries them.

<CodeGroup>
  ```python Python theme={null}
  from pinecone.grpc import PineconeGRPC, GRPCClientConfig
  from pinecone import ServerlessSpec

  # Initialize a client.
  # API key is required, but the value does not matter.
  # Host and port of the Pinecone Local instance
  # is required when starting without indexes. 
  pc = PineconeGRPC(
      api_key="pclocal", 
      host="http://localhost:5080" 
  )                                    

  # Create two indexes, one dense and one sparse
  dense_index_name = "dense-index"
  sparse_index_name = "sparse-index"

  if not pc.has_index(dense_index_name):  
      dense_index_model = pc.create_index(
          name=dense_index_name,
          vector_type="dense",
          dimension=2,
          metric="cosine",
          spec=ServerlessSpec(cloud="aws", region="us-east-1"),
          deletion_protection="disabled",
          tags={"environment": "development"}
      )

  print("Index model (dense):\n", dense_index_model)

  if not pc.has_index(sparse_index_name):  
      sparse_index_model = pc.create_index(
          name=sparse_index_name,
          vector_type="sparse",
          metric="dotproduct",
          spec=ServerlessSpec(cloud="aws", region="us-east-1"),
          deletion_protection="disabled",
          tags={"environment": "development"}
      )

  print("\nIndex model (sparse):\n", sparse_index_model)

  # Target each index, disabling tls
  dense_index_host = pc.describe_index(name=dense_index_name).host
  dense_index = pc.Index(host=dense_index_host, grpc_config=GRPCClientConfig(secure=False))
  sparse_index_host = pc.describe_index(name=sparse_index_name).host
  sparse_index = pc.Index(host=sparse_index_host, grpc_config=GRPCClientConfig(secure=False))

  # Upsert records into the index (dense)
  dense_index.upsert(
      vectors=[
          {
              "id": "vec1", 
              "values": [1.0, -2.5],
              "metadata": {"genre": "drama"}
          },
          {
              "id": "vec2", 
              "values": [3.0, -2.0],
              "metadata": {"genre": "documentary"}
          },
          {
              "id": "vec3", 
              "values": [0.5, -1.5],
              "metadata": {"genre": "documentary"}
          }
      ],
      namespace="example-namespace"
  )

  # Upsert records into the index (sparse)
  sparse_index.upsert(
      namespace="example-namespace",
      vectors=[
          {
              "id": "vec1",
              "sparse_values": {
                  "values": [1.7958984, 0.41577148, 2.828125, 2.8027344, 2.8691406, 1.6533203, 5.3671875, 1.3046875, 0.49780273, 0.5722656, 2.71875, 3.0820312, 2.5019531, 4.4414062, 3.3554688],
                  "indices": [822745112, 1009084850, 1221765879, 1408993854, 1504846510, 1596856843, 1640781426, 1656251611, 1807131503, 2543655733, 2902766088, 2909307736, 3246437992, 3517203014, 3590924191]
              },
              "metadata": {
                  "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.",
                  "category": "technology",
                  "quarter": "Q3"
              }
          },
          {
              "id": "vec2",
              "sparse_values": {
                  "values": [0.4362793, 3.3457031, 2.7714844, 3.0273438, 3.3164062, 5.6015625, 2.4863281, 0.38134766, 1.25, 2.9609375, 0.34179688, 1.4306641, 0.34375, 3.3613281, 1.4404297, 2.2558594, 2.2597656, 4.8710938, 0.5605469],
                  "indices": [131900689, 592326839, 710158994, 838729363, 1304885087, 1640781426, 1690623792, 1807131503, 2066971792, 2428553208, 2548600401, 2577534050, 3162218338, 3319279674, 3343062801, 3476647774, 3485013322, 3517203014, 4283091697]
              },
              "metadata": {
                  "chunk_text": "Analysts suggest that AAPL'\''s upcoming Q4 product launch event might solidify its position in the premium smartphone market.",
                  "category": "technology",
                  "quarter": "Q4"
              }
          },
          {
              "id": "vec3",
              "sparse_values": {
                  "values": [2.6875, 4.2929688, 3.609375, 3.0722656, 2.1152344, 5.78125, 3.7460938, 3.7363281, 1.2695312, 3.4824219, 0.7207031, 0.0826416, 4.671875, 3.7011719, 2.796875, 0.61621094],
                  "indices": [8661920, 350356213, 391213188, 554637446, 1024951234, 1640781426, 1780689102, 1799010313, 2194093370, 2632344667, 2641553256, 2779594451, 3517203014, 3543799498, 3837503950, 4283091697]
              },
              "metadata": {
                  "chunk_text": "AAPL'\''s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production",
                  "category": "technology",
                  "quarter": "Q3"
              }
          }
      ]
  )

  # Check the number of records in each index
  print("\nIndex stats (dense):\n", dense_index.describe_index_stats())
  print("\nIndex stats (sparse):\n", sparse_index.describe_index_stats())

  # Query the index (dense) with a metadata filter
  dense_response = dense_index.query(
      namespace="example-namespace",
      vector=[3.0, -2.0],
      filter={"genre": {"$eq": "documentary"}},
      top_k=1,
      include_values=False,
      include_metadata=True
  )

  print("\nDense query response:\n", dense_response)

  # Query the index (sparse) with a metadata filter
  sparse_response = sparse_index.query(
      namespace="example-namespace",
      sparse_vector={
        "values": [1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0],
        "indices": [767227209, 1640781426, 1690623792, 2021799277, 2152645940, 2295025838, 2443437770, 2779594451, 2956155693, 3476647774, 3818127854, 4283091697]
      }, 
      filter={
          "quarter": {"$eq": "Q4"}
      },
      top_k=1,
      include_values=False,
      include_metadata=True
  )

  print("/nSparse query response:\n", sparse_response)

  # Delete the indexes
  pc.delete_index(name=dense_index_name)
  pc.delete_index(name=sparse_index_name)
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone';

  // Initialize a client.
  // API key is required, but the value does not matter.
  // Host and port of the Pinecone Local instance
  // is required when starting without indexes.
  const pc = new Pinecone({ 
      apiKey: 'pclocal', 
      controllerHostUrl: 'http://localhost:5080' 
  });

  // Create two indexes, one dense and one sparse
  const denseIndexName = 'dense-index';
  const sparseIndexName = 'sparse-index';

  const denseIndexModel = await pc.createIndex({
    name: denseIndexName,
    vectorType: 'dense',
    dimension: 2,
    metric: 'cosine',
    spec: {
      serverless: {
        cloud: 'aws',
        region: 'us-east-1'
      }
    },
    deletionProtection: 'disabled',
    tags: { environment: 'development' }, 
  });

  console.log('Index model (dense):', denseIndexModel);

  const sparseIndexModel = await pc.createIndex({
      name: sparseIndexName,
      vectorType: 'sparse',
      metric: 'dotproduct',
      spec: {
        serverless: {
          cloud: 'aws',
          region: 'us-east-1'
        }
      },
      deletionProtection: 'disabled',
      tags: { environment: 'development' }, 
    });
    
  console.log('\nIndex model (sparse):', sparseIndexModel);
    
  // Target each index
  const denseIndexHost = (await pc.describeIndex(denseIndexName)).host;
  const denseIndex = await pc.index(denseIndexName, 'http://' + denseIndexHost);
  const sparseIndexHost = (await pc.describeIndex(sparseIndexName)).host;
  const sparseIndex = await pc.index(sparseIndexName, 'http://' + sparseIndexHost);

  // Upsert records into the index (dense)
  await denseIndex.namespace('example-namespace').upsert([
      {
          id: 'vec1', 
          values: [1.0, -2.5],
          metadata: { genre: 'drama' },
      },
      {
          id: 'vec2', 
          values: [3.0, -2.0],
          metadata: { genre: 'documentary' },
      },
      {
          id: 'vec3', 
          values: [0.5, -1.5],
          metadata: { genre: 'documentary' },
      }
  ]);

  // Upsert records into the index (sparse)
  await sparseIndex.namespace('example-namespace').upsert([
      {
          id: 'vec1',
          sparseValues: {
              indices: [822745112, 1009084850, 1221765879, 1408993854, 1504846510, 1596856843, 1640781426, 1656251611, 1807131503, 2543655733, 2902766088, 2909307736, 3246437992, 3517203014, 3590924191],
              values: [1.7958984, 0.41577148, 2.828125, 2.8027344, 2.8691406, 1.6533203, 5.3671875, 1.3046875, 0.49780273, 0.5722656, 2.71875, 3.0820312, 2.5019531, 4.4414062, 3.3554688]
          },
          metadata: { 
              chunk_text: 'AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.', 
              category: 'technology',
              quarter: 'Q3' 
          }
      },
      {
          id: 'vec2',
          sparseValues: {
              indices: [131900689, 592326839, 710158994, 838729363, 1304885087, 1640781426, 1690623792, 1807131503, 2066971792, 2428553208, 2548600401, 2577534050, 3162218338, 3319279674, 3343062801, 3476647774, 3485013322, 3517203014, 4283091697],
              values: [0.4362793, 3.3457031, 2.7714844, 3.0273438, 3.3164062, 5.6015625, 2.4863281, 0.38134766, 1.25, 2.9609375, 0.34179688, 1.4306641, 0.34375, 3.3613281, 1.4404297, 2.2558594, 2.2597656, 4.8710938, 0.5605469]
          },
          metadata: { 
              chunk_text: "Analysts suggest that AAPL's upcoming Q4 product launch event might solidify its position in the premium smartphone market.", 
              category: 'technology',
              quarter: 'Q4' 
          }
      },
      {
          id: 'vec3',
          sparseValues: {
              indices: [8661920, 350356213, 391213188, 554637446, 1024951234, 1640781426, 1780689102, 1799010313, 2194093370, 2632344667, 2641553256, 2779594451, 3517203014, 3543799498, 3837503950, 4283091697],
              values: [2.6875, 4.2929688, 3.609375, 3.0722656, 2.1152344, 5.78125, 3.7460938, 3.7363281, 1.2695312, 3.4824219, 0.7207031, 0.0826416, 4.671875, 3.7011719, 2.796875, 0.61621094]
          },
          metadata: { 
              chunk_text: "AAPL's strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production", 
              category: 'technology',
              quarter: 'Q3' 
          }
      }
  ]);
    
  // Check the number of records in each index
  console.log('\nIndex stats (dense):', await denseIndex.describeIndexStats());
  console.log('\nIndex stats (sparse):', await sparseIndex.describeIndexStats());

  // Query the index (dense) with a metadata filter
  const denseQueryResponse = await denseIndex.namespace('example-namespace').query({
      vector: [3.0, -2.0],
      filter: {
          'genre': {'$eq': 'documentary'}
      },
      topK: 1,
      includeValues: false,
      includeMetadata: true,
  });

  console.log('\nDense query response:', denseQueryResponse);

  const sparseQueryResponse = await sparseIndex.namespace('example-namespace').query({
      sparseVector: {
          indices: [767227209, 1640781426, 1690623792, 2021799277, 2152645940, 2295025838, 2443437770, 2779594451, 2956155693, 3476647774, 3818127854, 4283091697],
          values: [1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0]
      },
      topK: 1,
      includeValues: false,
      includeMetadata: true
  });

  console.log('\nSparse query response:', sparseQueryResponse);

  // Delete the index
  await pc.deleteIndex(denseIndexName);
  await pc.deleteIndex(sparseIndexName);
  ```

  ```java Java theme={null}
  import com.google.protobuf.Struct;
  import com.google.protobuf.Value;
  import io.pinecone.clients.Index;
  import io.pinecone.clients.Pinecone;
  import io.pinecone.proto.DescribeIndexStatsResponse;
  import org.openapitools.db_control.client.model.DeletionProtection;
  import io.pinecone.unsigned_indices_model.QueryResponseWithUnsignedIndices;

  import java.util.*;

  public class PineconeLocalExample {
      public static void main(String[] args) {
          // Initialize a client.
          // API key is required, but the value does not matter.
          // When starting without indexes, disable TLS and
          // provide the host and port of the Pinecone Local instance.
          String host = "http://localhost:5080";
          Pinecone pc = new Pinecone.Builder("pclocal")
                  .withHost(host)
                  .withTlsEnabled(false)
                  .build();

          // Create two indexes, one dense and one sparse
          String denseIndexName = "dense-index";
          String sparseIndexName = "sparse-index";
          HashMap<String, String> tags = new HashMap<>();
          tags.put("environment", "development");
          pc.createServerlessIndex(
                  denseIndexName,
                  "cosine",
                  2,
                  "aws",
                  "us-east-1",
                  DeletionProtection.DISABLED,
                  tags
          );
          pc.createSparseServelessIndex(
                  sparseIndexName,
                  "aws",
                  "us-east-1",
                  DeletionProtection.DISABLED,
                  tags,
                  "sparse"
          );

          // Get index connection objects
          Index denseIndexConnection = pc.getIndexConnection(denseIndexName);
          Index sparseIndexConnection = pc.getIndexConnection(sparseIndexName);

          // Upsert records into the index (dense)
          Struct metaData1 = Struct.newBuilder()
                  .putFields("genre", Value.newBuilder().setStringValue("drama").build())
                  .build();
          Struct metaData2 = Struct.newBuilder()
                  .putFields("genre", Value.newBuilder().setStringValue("documentary").build())
                  .build();
          Struct metaData3 = Struct.newBuilder()
                  .putFields("genre", Value.newBuilder().setStringValue("documentary").build())
                  .build();

          denseIndexConnection.upsert("vec1", Arrays.asList(1.0f, -2.5f),  null, null, metaData1, "example-namespace");
          denseIndexConnection.upsert("vec2", Arrays.asList(3.0f, -2.0f),  null, null, metaData2, "example-namespace");
          denseIndexConnection.upsert("vec3", Arrays.asList(0.5f, -1.5f),  null, null, metaData3, "example-namespace");

          // Upsert records into the index (sparse)
          ArrayList<Long> indices1 = new ArrayList<>(Arrays.asList(
                  822745112L, 1009084850L, 1221765879L, 1408993854L, 1504846510L,
                  1596856843L, 1640781426L, 1656251611L, 1807131503L, 2543655733L,
                  2902766088L, 2909307736L, 3246437992L, 3517203014L, 3590924191L
          ));

          ArrayList<Float> values1 = new ArrayList<>(Arrays.asList(
                  1.7958984f, 0.41577148f, 2.828125f, 2.8027344f, 2.8691406f,
                  1.6533203f, 5.3671875f, 1.3046875f, 0.49780273f, 0.5722656f,
                  2.71875f, 3.0820312f, 2.5019531f, 4.4414062f, 3.3554688f
          ));

          Struct sparseMetaData1 = Struct.newBuilder()
                  .putFields("chunk_text", Value.newBuilder().setStringValue("AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.").build())
                  .putFields("category", Value.newBuilder().setStringValue("technology").build())
                  .putFields("quarter", Value.newBuilder().setStringValue("Q3").build())
                  .build();

          ArrayList<Long> indices2 = new ArrayList<>(Arrays.asList(
                  131900689L, 592326839L, 710158994L, 838729363L, 1304885087L,
                  1640781426L, 1690623792L, 1807131503L, 2066971792L, 2428553208L,
                  2548600401L, 2577534050L, 3162218338L, 3319279674L, 3343062801L,
                  3476647774L, 3485013322L, 3517203014L, 4283091697L
          ));

          ArrayList<Float> values2 = new ArrayList<>(Arrays.asList(
                  0.4362793f, 3.3457031f, 2.7714844f, 3.0273438f, 3.3164062f,
                  5.6015625f, 2.4863281f, 0.38134766f, 1.25f, 2.9609375f,
                  0.34179688f, 1.4306641f, 0.34375f, 3.3613281f, 1.4404297f,
                  2.2558594f, 2.2597656f, 4.8710938f, 0.5605469f
          ));

          Struct sparseMetaData2 = Struct.newBuilder()
                  .putFields("chunk_text", Value.newBuilder().setStringValue("Analysts suggest that AAPL'\\''s upcoming Q4 product launch event might solidify its position in the premium smartphone market.").build())
                  .putFields("category", Value.newBuilder().setStringValue("technology").build())
                  .putFields("quarter", Value.newBuilder().setStringValue("Q4").build())
                  .build();

          ArrayList<Long> indices3 = new ArrayList<>(Arrays.asList(
                  8661920L, 350356213L, 391213188L, 554637446L, 1024951234L,
                  1640781426L, 1780689102L, 1799010313L, 2194093370L, 2632344667L,
                  2641553256L, 2779594451L, 3517203014L, 3543799498L,
                  3837503950L, 4283091697L
          ));

          ArrayList<Float> values3 = new ArrayList<>(Arrays.asList(
                  2.6875f, 4.2929688f, 3.609375f, 3.0722656f, 2.1152344f,
                  5.78125f, 3.7460938f, 3.7363281f, 1.2695312f, 3.4824219f,
                  0.7207031f, 0.0826416f, 4.671875f, 3.7011719f, 2.796875f,
                  0.61621094f
          ));

          Struct sparseMetaData3 = Struct.newBuilder()
                  .putFields("chunk_text", Value.newBuilder().setStringValue("AAPL'\\''s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production").build())
                  .putFields("category", Value.newBuilder().setStringValue("technology").build())
                  .putFields("quarter", Value.newBuilder().setStringValue("Q3").build())
                  .build();

          sparseIndexConnection.upsert("vec1", Collections.emptyList(), indices1, values1, sparseMetaData1, "example-namespace");
          sparseIndexConnection.upsert("vec2", Collections.emptyList(), indices2, values2, sparseMetaData2, "example-namespace");
          sparseIndexConnection.upsert("vec3", Collections.emptyList(), indices3, values3, sparseMetaData3, "example-namespace");

          // Check the number of records each the index
          DescribeIndexStatsResponse denseIndexStatsResponse = denseIndexConnection.describeIndexStats(null);
          System.out.println("Index stats (dense):");
          System.out.println(denseIndexStatsResponse);
          DescribeIndexStatsResponse sparseIndexStatsResponse = sparseIndexConnection.describeIndexStats(null);
          System.out.println("Index stats (sparse):");
          System.out.println(sparseIndexStatsResponse);

          // Query the index (dense) with a metadata filter
          List<Float> queryVector = Arrays.asList(1.0f, 1.5f);
          QueryResponseWithUnsignedIndices denseQueryResponse = denseIndexConnection.query(1, queryVector, null, null, null, "example-namespace", null, false, true);
          System.out.println("Dense query response:");
          System.out.println(denseQueryResponse);

          // Query the index (sparse) with a metadata filter
          List<Long> sparseIndices = Arrays.asList(
                  767227209L, 1640781426L, 1690623792L, 2021799277L, 2152645940L,
                  2295025838L, 2443437770L, 2779594451L, 2956155693L, 3476647774L,
                  3818127854L, 428309169L);
          List<Float> sparseValues = Arrays.asList(
                  1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f,
                  1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f);

          QueryResponseWithUnsignedIndices sparseQueryResponse = sparseIndexConnection.query(1, null, sparseIndices, sparseValues, null, "example-namespace", null, false, true);
          System.out.println("Sparse query response:");
          System.out.println(sparseQueryResponse);

          // Delete the indexes
          pc.deleteIndex(denseIndexName);
          pc.deleteIndex(sparseIndexName);
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
  	"context"
  	"encoding/json"
  	"fmt"
  	"log"

  	"github.com/pinecone-io/go-pinecone/v4/pinecone"
  	"google.golang.org/protobuf/types/known/structpb"
  )

  func prettifyStruct(obj interface{}) string {
  	bytes, _ := json.MarshalIndent(obj, "", "  ")
  	return string(bytes)
  }

  func main() {
  	ctx := context.Background()

  	// Initialize a client.
  	// No API key is required.
  	// Host and port of the Pinecone Local instance
  	// is required when starting without indexes.
  	pc, err := pinecone.NewClientBase(pinecone.NewClientBaseParams{
  		Host: "http://localhost:5080",
  	})
  	if err != nil {
  		log.Fatalf("Failed to create Client: %v", err)
  	}

  	// Create two indexes, one dense and one sparse
  	denseIndexName := "dense-index"
  	denseVectorType := "dense"
  	dimension := int32(2)
  	denseMetric := pinecone.Cosine
  	deletionProtection := pinecone.DeletionProtectionDisabled
  	denseIdx, err := pc.CreateServerlessIndex(ctx, &pinecone.CreateServerlessIndexRequest{
  		Name:               denseIndexName,
  		VectorType:         &denseVectorType,
  		Dimension:          &dimension,
  		Metric:             &denseMetric,
  		Cloud:              pinecone.Aws,
  		Region:             "us-east-1",
  		DeletionProtection: &deletionProtection,
  		Tags:               &pinecone.IndexTags{"environment": "development"},
  	})
  	if err != nil {
  		log.Fatalf("Failed to create serverless index: %v", denseIdx.Name)
  	} else {
  		fmt.Printf("Successfully created serverless index: %v\n", denseIdx.Name)
  	}

  	sparseIndexName := "sparse-index"
  	sparseVectorType := "sparse"
  	sparseMetric := pinecone.Dotproduct
  	sparseIdx, err := pc.CreateServerlessIndex(ctx, &pinecone.CreateServerlessIndexRequest{
  		Name:               sparseIndexName,
  		VectorType:         &sparseVectorType,
  		Metric:             &sparseMetric,
  		Cloud:              pinecone.Aws,
  		Region:             "us-east-1",
  		DeletionProtection: &deletionProtection,
  		Tags:               &pinecone.IndexTags{"environment": "development"},
  	})
  	if err != nil {
  		log.Fatalf("Failed to create serverless index: %v", sparseIdx.Name)
  	} else {
  		fmt.Printf("\nSuccessfully created serverless index: %v\n", sparseIdx.Name)
  	}

  	// Get the index hosts
  	denseIdxModel, err := pc.DescribeIndex(ctx, denseIndexName)
  	if err != nil {
  		log.Fatalf("Failed to describe index \"%v\": %v", denseIndexName, err)
  	}

  	sparseIdxModel, err := pc.DescribeIndex(ctx, sparseIndexName)
  	if err != nil {
  		log.Fatalf("Failed to describe index \"%v\": %v", sparseIndexName, err)
  	}

  	// Target the indexes.
  	// Make sure to prefix the hosts with http:// to let the SDK know to disable tls.
  	denseIdxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "http://" + denseIdxModel.Host, Namespace: "example-namespace"})
  	if err != nil {
  		log.Fatalf("Failed to create IndexConnection for Host: %v", err)
  	}

  	sparseIdxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "http://" + sparseIdxModel.Host, Namespace: "example-namespace"})
  	if err != nil {
  		log.Fatalf("Failed to create IndexConnection for Host: %v", err)
  	}

  	// Upsert records into the index (dense)
  	denseMetadataMap1 := map[string]interface{}{
  		"genre": "drama",
  	}

  	denseMetadata1, err := structpb.NewStruct(denseMetadataMap1)
  	if err != nil {
  		log.Fatalf("Failed to create metadata map: %v", err)
  	}

  	denseMetadataMap2 := map[string]interface{}{
  		"genre": "documentary",
  	}

  	denseMetadata2, err := structpb.NewStruct(denseMetadataMap2)
  	if err != nil {
  		log.Fatalf("Failed to create metadata map: %v", err)
  	}

  	denseMetadataMap3 := map[string]interface{}{
  		"genre": "documentary",
  	}

  	denseMetadata3, err := structpb.NewStruct(denseMetadataMap3)
  	if err != nil {
  		log.Fatalf("Failed to create metadata map: %v", err)
  	}

  	denseVectors := []*pinecone.Vector{
  		{
  			Id:       "vec1",
  			Values:   &[]float32{1.0, -2.5},
  			Metadata: denseMetadata1,
  		},
  		{
  			Id:       "vec2",
  			Values:   &[]float32{3.0, -2.0},
  			Metadata: denseMetadata2,
  		},
  		{
  			Id:       "vec3",
  			Values:   &[]float32{0.5, -1.5},
  			Metadata: denseMetadata3,
  		},
  	}

  	denseCount, err := denseIdxConnection.UpsertVectors(ctx, denseVectors)
  	if err != nil {
  		log.Fatalf("Failed to upsert vectors: %v", err)
  	} else {
  		fmt.Printf("\nSuccessfully upserted %d vector(s)!\n", denseCount)
  	}

  	// Upsert records into the index (sparse)
  	sparseValues1 := pinecone.SparseValues{
  		Indices: []uint32{822745112, 1009084850, 1221765879, 1408993854, 1504846510, 1596856843, 1640781426, 1656251611, 1807131503, 2543655733, 2902766088, 2909307736, 3246437992, 3517203014, 3590924191},
  		Values:  []float32{1.7958984, 0.41577148, 2.828125, 2.8027344, 2.8691406, 1.6533203, 5.3671875, 1.3046875, 0.49780273, 0.5722656, 2.71875, 3.0820312, 2.5019531, 4.4414062, 3.3554688},
  	}

  	sparseMetadataMap1 := map[string]interface{}{
  		"chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones",
  		"category":   "technology",
  		"quarter":    "Q3",
  	}

  	sparseMetadata1, err := structpb.NewStruct(sparseMetadataMap1)
  	if err != nil {
  		log.Fatalf("Failed to create metadata map: %v", err)
  	}

  	sparseValues2 := pinecone.SparseValues{
  		Indices: []uint32{131900689, 592326839, 710158994, 838729363, 1304885087, 1640781426, 1690623792, 1807131503, 2066971792, 2428553208, 2548600401, 2577534050, 3162218338, 3319279674, 3343062801, 3476647774, 3485013322, 3517203014, 4283091697},
  		Values:  []float32{0.4362793, 3.3457031, 2.7714844, 3.0273438, 3.3164062, 5.6015625, 2.4863281, 0.38134766, 1.25, 2.9609375, 0.34179688, 1.4306641, 0.34375, 3.3613281, 1.4404297, 2.2558594, 2.2597656, 4.8710938, 0.560546},
  	}

  	sparseMetadataMap2 := map[string]interface{}{
  		"chunk_text": "Analysts suggest that AAPL's upcoming Q4 product launch event might solidify its position in the premium smartphone market.",
  		"category":   "technology",
  		"quarter":    "Q4",
  	}

  	sparseMetadata2, err := structpb.NewStruct(sparseMetadataMap2)
  	if err != nil {
  		log.Fatalf("Failed to create metadata map: %v", err)
  	}

  	sparseValues3 := pinecone.SparseValues{
  		Indices: []uint32{8661920, 350356213, 391213188, 554637446, 1024951234, 1640781426, 1780689102, 1799010313, 2194093370, 2632344667, 2641553256, 2779594451, 3517203014, 3543799498, 3837503950, 4283091697},
  		Values:  []float32{2.6875, 4.2929688, 3.609375, 3.0722656, 2.1152344, 5.78125, 3.7460938, 3.7363281, 1.2695312, 3.4824219, 0.7207031, 0.0826416, 4.671875, 3.7011719, 2.796875, 0.61621094},
  	}

  	sparseMetadataMap3 := map[string]interface{}{
  		"chunk_text": "AAPL's strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production",
  		"category":   "technology",
  		"quarter":    "Q3",
  	}

  	sparseMetadata3, err := structpb.NewStruct(sparseMetadataMap3)
  	if err != nil {
  		log.Fatalf("Failed to create metadata map: %v", err)
  	}

  	sparseVectors := []*pinecone.Vector{
  		{
  			Id:           "vec1",
  			SparseValues: &sparseValues1,
  			Metadata:     sparseMetadata1,
  		},
  		{
  			Id:           "vec2",
  			SparseValues: &sparseValues2,
  			Metadata:     sparseMetadata2,
  		},
  		{
  			Id:           "vec3",
  			SparseValues: &sparseValues3,
  			Metadata:     sparseMetadata3,
  		},
  	}

  	sparseCount, err := sparseIdxConnection.UpsertVectors(ctx, sparseVectors)
  	if err != nil {
  		log.Fatalf("Failed to upsert vectors: %v", err)
  	} else {
  		fmt.Printf("\nSuccessfully upserted %d vector(s)!\n", sparseCount)
  	}

  	// Check the number of records in each index
  	denseStats, err := denseIdxConnection.DescribeIndexStats(ctx)
  	if err != nil {
  		log.Fatalf("Failed to describe index: %v", err)
  	} else {
  		fmt.Printf("\nIndex stats (dense): %+v\n", prettifyStruct(*denseStats))
  	}

  	sparseStats, err := sparseIdxConnection.DescribeIndexStats(ctx)
  	if err != nil {
  		log.Fatalf("Failed to describe index: %v", err)
  	} else {
  		fmt.Printf("\nIndex stats (sparse): %+v\n", prettifyStruct(*sparseStats))
  	}

  	// Query the index (dense) with a metadata filter
  	queryVector := []float32{3.0, -2.0}

  	queryMetadataMap := map[string]interface{}{
  		"genre": map[string]interface{}{
  			"$eq": "documentary",
  		},
  	}

  	metadataFilter, err := structpb.NewStruct(queryMetadataMap)
  	if err != nil {
  		log.Fatalf("Failed to create metadata map: %v", err)
  	}

  	denseRes, err := denseIdxConnection.QueryByVectorValues(ctx, &pinecone.QueryByVectorValuesRequest{
  		Vector:          queryVector,
  		TopK:            1,
  		MetadataFilter:  metadataFilter,
  		IncludeValues:   false,
  		IncludeMetadata: true,
  	})
  	if err != nil {
  		log.Fatalf("Error encountered when querying by vector: %v", err)
  	} else {
  		fmt.Printf("\nDense query response: %v\n", prettifyStruct(denseRes))
  	}

  	// Query the index (sparse) with a metadata filter

  	sparseValues := pinecone.SparseValues{
  		Indices: []uint32{767227209, 1640781426, 1690623792, 2021799277, 2152645940, 2295025838, 2443437770, 2779594451, 2956155693, 3476647774, 3818127854, 4283091697},
  		Values:  []float32{1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0},
  	}

  	sparseRes, err := sparseIdxConnection.QueryByVectorValues(ctx, &pinecone.QueryByVectorValuesRequest{
  		SparseValues:    &sparseValues,
  		TopK:            1,
  		IncludeValues:   false,
  		IncludeMetadata: true,
  	})
  	if err != nil {
  		log.Fatalf("Error encountered when querying by vector: %v", err)
  	} else {
  		fmt.Printf("\nSparse query response: %v\n", prettifyStruct(sparseRes))
  	}
  	// Delete the indexes
  	err = pc.DeleteIndex(ctx, denseIndexName)
  	if err != nil {
  		log.Fatalf("Failed to delete index: %v", err)
  	} else {
  		fmt.Printf("\nIndex \"%v\" deleted successfully\n", denseIndexName)
  	}

  	err = pc.DeleteIndex(ctx, sparseIndexName)
  	if err != nil {
  		log.Fatalf("Failed to delete index: %v", err)
  	} else {
  		fmt.Printf("\nIndex \"%v\" deleted successfully\n", sparseIndexName)
  	}
  }
  ```

  ```shell curl theme={null}
  PINECONE_LOCAL_HOST="localhost:5080"
  DENSE_INDEX_HOST="localhost:5081"
  SPARSE_INDEX_HOST="localhost:5082"

  # Create two indexes, one dense and one sparse
  curl -X POST "http://$PINECONE_LOCAL_HOST/indexes" \
      -H "Accept: application/json" \
      -H "Content-Type: application/json" \
      -H "X-Pinecone-Api-Version: 2025-10" \
      -d '{
              "name": "dense-index",
              "vector_type": "dense",
              "dimension": 2,
              "metric": "cosine",
              "spec": {
                  "serverless": {
                      "cloud": "aws",
                      "region": "us-east-1"
                  }
              },
              "tags": {
                  "environment": "development"
              },
              "deletion_protection": "disabled"
          }'

  curl -X POST "http://$PINECONE_LOCAL_HOST/indexes" \
      -H "Accept: application/json" \
      -H "Content-Type: application/json" \
      -H "X-Pinecone-Api-Version: 2025-10" \
      -d '{
              "name": "sparse-index",
              "vector_type": "sparse",
              "metric": "dotproduct",
              "spec": {
                  "serverless": {
                      "cloud": "aws",
                      "region": "us-east-1"
                  }
              },
              "tags": {
                  "environment": "development"
              },
              "deletion_protection": "disabled"
          }'

  # Upsert records into the index (dense)
  curl -X POST "http://$DENSE_INDEX_HOST/vectors/upsert" \
      -H "Content-Type: application/json" \
      -H "X-Pinecone-Api-Version: 2025-10" \
      -d '{
              "namespace": "example-namespace",
              "vectors": [
                  {
                      "id": "vec1", 
                      "values": [1.0, -2.5],
                      "metadata": {"genre": "drama"}
                  },
                  {
                      "id": "vec2", 
                      "values": [3.0, -2.0],
                      "metadata": {"genre": "documentary"}
                  },
                  {
                      "id": "vec3", 
                      "values": [0.5, -1.5],
                      "metadata": {"genre": "documentary"}
                  }
              ]
          }'

  # Upsert records into the index (sparse)
  curl -X POST "http://$SPARSE_INDEX_HOST/vectors/upsert" \
      -H "Content-Type: application/json" \
      -H "X-Pinecone-Api-Version: 2025-10" \
      -d '{
              "namespace": "example-namespace",
              "vectors": [
                  {
                      "id": "vec1",
                      "sparseValues": {
                          "values": [1.7958984, 0.41577148, 2.828125, 2.8027344, 2.8691406, 1.6533203, 5.3671875, 1.3046875, 0.49780273, 0.5722656, 2.71875, 3.0820312, 2.5019531, 4.4414062, 3.3554688],
                          "indices": [822745112, 1009084850, 1221765879, 1408993854, 1504846510, 1596856843, 1640781426, 1656251611, 1807131503, 2543655733, 2902766088, 2909307736, 3246437992, 3517203014, 3590924191]
                      },
                      "metadata": {
                          "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.",
                          "category": "technology",
                          "quarter": "Q3"
                      }
                  },
                  {
                      "id": "vec2",
                      "sparseValues": {
                          "values": [0.4362793, 3.3457031, 2.7714844, 3.0273438, 3.3164062, 5.6015625, 2.4863281, 0.38134766, 1.25, 2.9609375, 0.34179688, 1.4306641, 0.34375, 3.3613281, 1.4404297, 2.2558594, 2.2597656, 4.8710938, 0.5605469],
                          "indices": [131900689, 592326839, 710158994, 838729363, 1304885087, 1640781426, 1690623792, 1807131503, 2066971792, 2428553208, 2548600401, 2577534050, 3162218338, 3319279674, 3343062801, 3476647774, 3485013322, 3517203014, 4283091697]
                      },
                      "metadata": {
                          "chunk_text": "Analysts suggest that AAPL'\''s upcoming Q4 product launch event might solidify its position in the premium smartphone market.",
                          "category": "technology",
                          "quarter": "Q4"
                      }
                  },
                  {
                      "id": "vec3",
                      "sparseValues": {
                          "values": [2.6875, 4.2929688, 3.609375, 3.0722656, 2.1152344, 5.78125, 3.7460938, 3.7363281, 1.2695312, 3.4824219, 0.7207031, 0.0826416, 4.671875, 3.7011719, 2.796875, 0.61621094],
                          "indices": [8661920, 350356213, 391213188, 554637446, 1024951234, 1640781426, 1780689102, 1799010313, 2194093370, 2632344667, 2641553256, 2779594451, 3517203014, 3543799498, 3837503950, 4283091697]
                      },
                      "metadata": {
                          "chunk_text": "AAPL'\''s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production",
                          "category": "technology",
                          "quarter": "Q3"
                      }
                  }
              ]
          }'

  # Check the number of records in each index
  curl -X POST "http://$DENSE_INDEX_HOST/describe_index_stats" \
      -H "Content-Type: application/json" \
      -H "X-Pinecone-Api-Version: 2025-10" \
      -d '{}'

  curl -X POST "http://$SPARSE_INDEX_HOST/describe_index_stats" \
      -H "Content-Type: application/json" \
      -H "X-Pinecone-Api-Version: 2025-10" \
      -d '{}'

  # Query the index (dense) with a metadata filter
  curl "http://$DENSE_INDEX_HOST/query" \
      -H "Content-Type: application/json" \
      -H "X-Pinecone-Api-Version: 2025-10" \
      -d '{
              "vector": [3.0, -2.0],
              "filter": {"genre": {"$eq": "documentary"}},
              "topK": 1,
              "includeMetadata": true,
              "includeValues": false,
              "namespace": "example-namespace"
          }'

  # Query the index (sparse) with a metadata filter
  curl "http://$SPARSE_INDEX_HOST/query" \
      -H "Content-Type: application/json" \
      -H "X-Pinecone-Api-Version: 2025-10" \
      -d '{
              "sparseVector": {
                  "values": [1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0],
                  "indices": [767227209, 1640781426, 1690623792, 2021799277, 2152645940, 2295025838, 2443437770, 2779594451, 2956155693, 3476647774, 3818127854, 4283091697]
              },
              "filter": {"quarter": {"$eq": "Q4"}},
              "namespace": "example-namespace",
              "topK": 1,
              "includeMetadata": true,
              "includeValues": false
          }'

  # Delete the index
  curl -X DELETE "http://$PINECONE_LOCAL_HOST/indexes/dense-index" \
      -H "X-Pinecone-Api-Version: 2025-10"

  curl -X DELETE "http://$PINECONE_LOCAL_HOST/indexes/sparse-index" \
      -H "X-Pinecone-Api-Version: 2025-10"
  ```
</CodeGroup>

## 2. Set up GitHub Actions

[Set up a GitHub Actions workflow](https://docs.github.com/en/actions/writing-workflows/quickstart) to do the following:

1. Pull the Pinecone Local Docker image.
2. Start a Pinecone Local instance for each test run.
3. Execute tests against the local instance.
4. Tear down the instance after tests complete.

Here's a sample GitHub Actions workflow that you can extend for your own needs:

```yaml theme={null}
name: CI/CD with Pinecone Local
on:
  pull_request:
    branches:
      - main
  push:
    branches:
      - main

jobs:
  pc-local-tests:
    name: Pinecone Local tests
    runs-on: ubuntu-latest
    services:
      pc-local:
        image: ghcr.io/pinecone-io/pinecone-local:latest
        env:
          PORT: 5080
        ports:
          - "5080-6000:5080-6000"
    steps:
      - name: Check out repository code
        uses: actions/checkout@v4

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install "pinecone[grpc]"

      - name: Run tests
        run: |
          pytest test/
```

## 3. Run your tests

GitHub Actions will automaticaly run your tests against Pinecone Local when the events you specified in your workflow occur.

For a list of the events that can trigger a workflow and more details about using GitHub Actions for CI/CD, see the [GitHub Actions documentation](https://docs.github.com/en/actions).


# Bring your own cloud (BYOC)
Source: https://docs.pinecone.io/guides/production/bring-your-own-cloud

Deploy Pinecone BYOC in your own AWS, GCP, or Azure account for data sovereignty, network isolation, and regional data residency requirements.

<Note>
  BYOC is in [public preview](/release-notes/feature-availability) on AWS, GCP, and Azure.
</Note>

Pinecone BYOC (bring your own cloud) is designed for organizations with strict requirements around data sovereignty, network isolation, and data residency.

With BYOC, you deploy the Pinecone data plane in your own cloud account (AWS, GCP, or Azure), and you get the benefits of a managed service — upgrades, scaling, and maintenance — without giving up control of your data or infrastructure.

Pinecone never has direct access to your cloud account. Your vectors, metadata, and queries never leave your environment, and no inbound network access is required. An agent in your cluster pulls operations from Pinecone and executes them locally.

<img alt="BYOC architecture diagram" />

<img alt="BYOC architecture diagram" />

BYOC uses a split architecture:

* The data plane runs entirely in your cloud account within a dedicated VPC, storing and processing your vectors, executing queries, and managing index data in object storage (S3 on AWS, GCS on GCP, or Azure Blob Storage on Azure).
* The control plane is managed by Pinecone globally and handles index lifecycle management, authentication, billing, and user management, but never stores or processes your vectors.

For maintenance, the agent authenticates with Pinecone's control plane, pulls pending operations (upgrades, scaling, etc.), and executes them locally. All operations are stored as Kubernetes CRDs, providing a complete audit trail.

Only operational metrics (CPU, memory, latency) and traces are transmitted to Pinecone for monitoring; customer data is filtered out before transmission.

## Encryption and customer-managed keys

In the **standard Pinecone service**, [customer-managed encryption keys (CMEK)](/guides/production/configure-cmek) are how you connect Pinecone-managed storage to **your** AWS KMS keys through the Pinecone console.

In **BYOC**, your vectors and index data are stored in **your** cloud account (for example object storage, databases, and block volumes). You apply your cloud provider’s KMS to those resources using the same native controls you use for other workloads (key policies, rotation, and compliance programs such as PCI or ISO 27001). When you deploy with [pulumi-pinecone-byoc](https://github.com/pinecone-io/pulumi-pinecone-byoc), you can supply your KMS key where the template supports it; see that repository’s README for current options. This is not the console **CMEK** flow used for hosted projects.

## Prerequisites

Before deploying BYOC, ensure you have the following tools installed on your local machine:

| Tool         | Purpose                | Install                                                                      |
| ------------ | ---------------------- | ---------------------------------------------------------------------------- |
| Python 3.12+ | Runtime                | [python.org](https://www.python.org/downloads/)                              |
| uv           | Package manager        | [docs.astral.sh/uv](https://docs.astral.sh/uv/getting-started/installation/) |
| Pulumi       | Infrastructure-as-code | [pulumi.com/docs/install](https://www.pulumi.com/docs/install/)              |
| kubectl      | Cluster access         | [kubernetes.io](https://kubernetes.io/docs/tasks/tools/)                     |

You also need:

* The CLI for your cloud provider:
  * **AWS**: [AWS CLI v2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)
  * **GCP**: [gcloud CLI](https://cloud.google.com/sdk/docs/install)
  * **Azure**: [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli)
* A cloud account with admin-level permissions:
  * **AWS**: `AdministratorAccess`. `PowerUserAccess` is not sufficient because BYOC creates IAM roles and policies.
  * **GCP**: `roles/owner`. `roles/editor` is not sufficient because BYOC creates IAM service accounts and bindings.
  * **Azure**: `Owner` on the subscription. `Contributor` is not sufficient because BYOC creates managed identities and role assignments.
* Sufficient cloud quota for the resources (the setup wizard validates this)
* A Pinecone API key from the Pinecone console.
* A Pinecone Enterprise plan (required for BYOC access)

<Note>
  If you install any new tools, open a new terminal session before proceeding so that your shell picks up the updated PATH and environment.
</Note>

## Deploy BYOC

To deploy BYOC, follow these steps:

<Steps>
  <Step title="Run the setup wizard">
    Run the bootstrap script from the BYOC deployment repository ([github.com/pinecone-io/pulumi-pinecone-byoc](https://github.com/pinecone-io/pulumi-pinecone-byoc)) to start the interactive setup wizard:

    ```bash theme={null}
    curl -fsSL https://raw.githubusercontent.com/pinecone-io/pulumi-pinecone-byoc/main/bootstrap.sh | bash
    ```

    You can also pre-select your cloud provider:

    ```bash theme={null}
    # AWS
    curl -fsSL https://raw.githubusercontent.com/pinecone-io/pulumi-pinecone-byoc/main/bootstrap.sh | bash -s -- --cloud aws

    # GCP
    curl -fsSL https://raw.githubusercontent.com/pinecone-io/pulumi-pinecone-byoc/main/bootstrap.sh | bash -s -- --cloud gcp

    # Azure
    curl -fsSL https://raw.githubusercontent.com/pinecone-io/pulumi-pinecone-byoc/main/bootstrap.sh | bash -s -- --cloud azure
    ```

    The script selects your cloud provider, checks that required tools are installed, verifies your cloud credentials, then launches an interactive wizard that collects your configuration choices, validates your quotas, and generates a Pulumi project. No cloud resources are created during this step.

    <Accordion title="Setup wizard prompts">
      The wizard prompts you for the following:

      | Prompt                    | Description                                                                                                                                    | Default                                                    |
      | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
      | **Cloud provider**        | Select AWS, GCP, or Azure (skipped if pre-selected via `--cloud`).                                                                             | -                                                          |
      | **Pinecone API key**      | Your API key from the Pinecone console (or uses `PINECONE_API_KEY` env var).                                                                   | -                                                          |
      | **Cloud credentials**     | Validates credentials and displays your account/project/subscription ID.                                                                       | -                                                          |
      | **GCP project ID**        | *(GCP only)* Your GCP project ID.                                                                                                              | Detected from `gcloud`                                     |
      | **Azure subscription ID** | *(Azure only)* Your Azure subscription ID.                                                                                                     | Detected from `az account show`                            |
      | **Region**                | Region for deployment.                                                                                                                         | `us-east-1` (AWS) / `us-central1` (GCP) / `eastus` (Azure) |
      | **Availability zones**    | Zones for high availability. Wizard fetches available options.                                                                                 | First two zones                                            |
      | **Custom AMI**            | *(AWS only)* Custom AMI ID for EKS nodes. Leave blank for the default AWS AMI.                                                                 | None                                                       |
      | **VPC CIDR block**        | IP range for your VPC/VNet. Choose a range that doesn't conflict with existing networks.                                                       | `10.0.0.0/16` (AWS/Azure) / `10.112.0.0/12` (GCP)          |
      | **Deletion protection**   | Protect databases and storage from accidental deletion.                                                                                        | Enabled                                                    |
      | **Network access**        | Public access (connect from anywhere) or private only (requires PrivateLink on AWS, Private Service Connect on GCP, or Private Link on Azure). | Public enabled                                             |
      | **Resource tags/labels**  | Custom tags (AWS/Azure) or labels (GCP) for cost tracking (e.g., `team=platform,env=prod`).                                                    | None                                                       |
      | **Preflight checks**      | Validates cloud quotas. If checks fail, request quota increases before proceeding.                                                             | -                                                          |
      | **Project name**          | Name for your deployment.                                                                                                                      | `pinecone-byoc`                                            |
      | **Pulumi backend**        | Where to store state: local (`~/.pulumi` with passphrase) or Pulumi Cloud.                                                                     | Local                                                      |
    </Accordion>

    After completing the wizard, a Pulumi project is generated in your project directory.

    <Accordion title="Generated configuration file">
      The wizard creates a `Pulumi.<stack>.yaml` file with configurable options. The options vary by cloud provider:

      <Tabs>
        <Tab title="AWS">
          | Option                  | Description                                         | Default                        |
          | ----------------------- | --------------------------------------------------- | ------------------------------ |
          | `pinecone-version`      | Pinecone release version                            | -                              |
          | `region`                | AWS region                                          | `us-east-1`                    |
          | `availability-zones`    | Availability zones for high availability            | `["us-east-1a", "us-east-1b"]` |
          | `vpc-cidr`              | VPC IP range                                        | `10.0.0.0/16`                  |
          | `deletion-protection`   | Protect RDS and S3 from accidental deletion         | `true`                         |
          | `public-access-enabled` | Enable public endpoint (`false` = PrivateLink only) | `true`                         |
          | `custom-ami-id`         | Custom AMI ID for EKS nodes                         | Default AWS AMI                |
          | `tags`                  | Custom tags for all AWS resources                   | `{}`                           |
        </Tab>

        <Tab title="GCP">
          | Option                  | Description                                                     | Default                              |
          | ----------------------- | --------------------------------------------------------------- | ------------------------------------ |
          | `gcp:project`           | GCP project ID                                                  | -                                    |
          | `pinecone-version`      | Pinecone release version                                        | -                                    |
          | `region`                | GCP region                                                      | `us-central1`                        |
          | `availability-zones`    | Zones for high availability                                     | `["us-central1-a", "us-central1-b"]` |
          | `vpc-cidr`              | VPC IP range                                                    | `10.112.0.0/12`                      |
          | `deletion-protection`   | Protect AlloyDB and GCS from accidental deletion                | `true`                               |
          | `public-access-enabled` | Enable public endpoint (`false` = Private Service Connect only) | `true`                               |
          | `labels`                | Custom labels for all GCP resources                             | `{}`                                 |
        </Tab>

        <Tab title="Azure">
          | Option                  | Description                                                             | Default       |
          | ----------------------- | ----------------------------------------------------------------------- | ------------- |
          | `subscription-id`       | Azure subscription ID                                                   | -             |
          | `pinecone-version`      | Pinecone release version                                                | -             |
          | `region`                | Azure region                                                            | `eastus`      |
          | `availability-zones`    | Zones for high availability                                             | `["1", "2"]`  |
          | `vpc-cidr`              | VNet IP range                                                           | `10.0.0.0/16` |
          | `deletion-protection`   | Protect PostgreSQL Flexible Server and storage from accidental deletion | `true`        |
          | `public-access-enabled` | Enable public endpoint (`false` = Private Link only)                    | `true`        |
          | `tags`                  | Custom tags for all Azure resources                                     | `{}`          |
        </Tab>
      </Tabs>

      To change configuration after initial setup, edit `Pulumi.<stack>.yaml` and run `pulumi up`.
    </Accordion>

    <Accordion title="Programmatic usage">
      For advanced users who want to integrate BYOC into existing Pulumi infrastructure, the `pulumi-pinecone-byoc` package is available on [PyPI](https://pypi.org/project/pulumi-pinecone-byoc/). Install with cloud-specific dependencies:

      ```bash theme={null}
      # For AWS
      uv add 'pulumi-pinecone-byoc[aws]'

      # For GCP
      uv add 'pulumi-pinecone-byoc[gcp]'

      # For Azure
      uv add 'pulumi-pinecone-byoc[azure]'
      ```

      Import the cluster class for your cloud provider:

      ```python theme={null}
      # AWS
      from pulumi_pinecone_byoc.aws import PineconeAWSCluster, PineconeAWSClusterArgs

      # GCP
      from pulumi_pinecone_byoc.gcp import PineconeGCPCluster, PineconeGCPClusterArgs

      # Azure
      from pulumi_pinecone_byoc.azure import PineconeAzureCluster, PineconeAzureClusterArgs
      ```

      See the [repository README](https://github.com/pinecone-io/pulumi-pinecone-byoc#programmatic-usage) for full usage examples.
    </Accordion>
  </Step>

  <Step title="Deploy the infrastructure">
    Deploy the generated Pulumi project to create your cloud resources:

    ```bash theme={null}
    cd pinecone-byoc
    pulumi up
    ```

    Pulumi shows a preview of all resources to be created. Confirm to proceed. Provisioning takes approximately 25-30 minutes.

    When complete, the output displays:

    * Your BYOC **environment name** (used when creating indexes).
    * The **kubectl command** to configure cluster access.

    <Accordion title="Infrastructure provisioned">
      The deployment creates the following resources in your cloud account:

      | Component            | AWS                                                             | GCP                                                 | Azure                                            |
      | -------------------- | --------------------------------------------------------------- | --------------------------------------------------- | ------------------------------------------------ |
      | **VPC / Networking** | VPC, public and private subnets, NAT gateways, internet gateway | VPC network, subnets, Cloud NAT, Cloud Router       | VNet, subnets, NAT gateway                       |
      | **Kubernetes**       | EKS cluster with managed node groups                            | GKE cluster with node pools                         | AKS cluster with agent pools                     |
      | **Object storage**   | S3 buckets (data, WAL, backups)                                 | GCS buckets (data, WAL, backups)                    | Blob Storage containers (data, WAL, backups)     |
      | **Database**         | Aurora PostgreSQL (RDS)                                         | AlloyDB                                             | PostgreSQL Flexible Server                       |
      | **Load balancing**   | Network Load Balancer                                           | Internal load balancer with Private Service Connect | Internal load balancer with Private Link Service |
      | **DNS**              | Route 53 hosted zone                                            | Cloud DNS managed zone                              | Azure DNS zone                                   |
      | **TLS certificates** | AWS Certificate Manager                                         | cert-manager                                        | cert-manager                                     |
      | **IAM**              | IAM roles and policies                                          | Service accounts and Workload Identity              | Managed identities and Workload Identity         |

      The initial deployment provisions 3 Kubernetes nodes. After setup, the cluster autoscales based on the services Pinecone deploys and your workload.
    </Accordion>
  </Step>

  <Step title="Verify the deployment">
    Configure `kubectl` to connect to your cluster using the command from the deployment output:

    <Tabs>
      <Tab title="AWS">
        ```bash theme={null}
        aws eks update-kubeconfig --region <region> --name <cluster-name>
        ```
      </Tab>

      <Tab title="GCP">
        ```bash theme={null}
        gcloud container clusters get-credentials <cluster-name> --region <region> --project <project-id>
        ```
      </Tab>

      <Tab title="Azure">
        ```bash theme={null}
        az aks get-credentials --resource-group <resource-group> --name <cluster-name>
        ```
      </Tab>
    </Tabs>

    The above command configures your local `kubectl` tool to communicate with your Kubernetes cluster. You'll use cluster access for administrative tasks like viewing operations and troubleshooting. Creating indexes and reading/writing vectors still use the standard Pinecone API.

    Verify all components are running:

    ```bash theme={null}
    # Check that all pods are running
    kubectl get pods -A | grep -E "(pinecone|pc-)"
    ```

    All pods should show `Running` status. If any pods are in `Pending` or `CrashLoopBackOff`, check the [Troubleshooting](#troubleshooting) section.

    You can also verify the cluster operations CRD is installed:

    ```bash theme={null}
    kubectl get cluster-operations
    ```

    It's normal to see "No resources found" on a fresh deployment. Operations appear here as Pinecone performs upgrades and other management tasks.
  </Step>
</Steps>

## Use BYOC

Once your BYOC environment is deployed, you can create indexes and read/write data using the standard Pinecone API.

### Control plane operations

Control plane operations like [creating](/reference/api/latest/control-plane/create_index), [listing](/reference/api/latest/control-plane/list_indexes), and [deleting](/reference/api/latest/control-plane/delete_index) indexes work via the standard Pinecone API regardless of your network access mode.

<Note>
  BYOC supports [dedicated read nodes](/guides/index-data/dedicated-read-nodes) indexes, but not on-demand indexes.
</Note>

<Accordion title="Create an index">
  Use the environment name from the deployment output to create indexes in your BYOC environment. BYOC supports [dedicated read nodes](/guides/index-data/dedicated-read-nodes) indexes only.

  <CodeGroup>
    ```bash curl theme={null}
    PINECONE_API_KEY="YOUR_API_KEY"

    curl -X POST "https://api.pinecone.io/indexes" \
         -H "Accept: application/json" \
         -H "Content-Type: application/json" \
         -H "Api-Key: $PINECONE_API_KEY" \
         -H "X-Pinecone-Api-Version: 2025-10" \
         -d '{
               "name": "example-byoc-index",
               "dimension": 1536,
               "metric": "cosine",
               "vector_type": "dense",
               "spec": {
                 "byoc": {
                   "environment": "aws-us-east-1-26bf.byoc",
                   "read_capacity": {
                     "mode": "Dedicated",
                     "dedicated": {
                       "node_type": "b1",
                       "scaling": "Manual",
                       "manual": {
                         "shards": 1,
                         "replicas": 1
                       }
                     }
                   }
                 }
               },
               "deletion_protection": "disabled"
             }'
    ```

    ```python Python theme={null}
    from pinecone import Pinecone
    from pinecone.db_control.models import ByocSpec

    pc = Pinecone(api_key="YOUR_API_KEY")

    pc.db.index.create(
        name="example-byoc-index",
        dimension=1536,
        metric="cosine",
        vector_type="dense",
        spec=ByocSpec(
            environment="aws-us-east-1-26bf.byoc",
            read_capacity={
                "mode": "Dedicated",
                "dedicated": {
                    "node_type": "b1",
                    "scaling": "Manual",
                    "manual": {
                        "shards": 1,
                        "replicas": 1,
                    },
                },
            },
        ),
        deletion_protection="disabled",
    )
    ```
  </CodeGroup>
</Accordion>

### Data plane operations

Data plane operations like [querying](/reference/api/latest/data-plane/query), [upserting](/reference/api/latest/data-plane/upsert), and [fetching](/reference/api/latest/data-plane/fetch) vectors depend on your network access mode.

<Note>
  BYOC does not support reading and writing data from the index browser in the Pinecone console.
</Note>

<AccordionGroup>
  <Accordion title="Public access enabled (default)">
    Use the `host` URL from the Pinecone console or the [Describe an index](/reference/api/latest/control-plane/describe_index) API response. For example:

    ```
    https://my-index-abc123.svc.us-east-1.byoc.pinecone.io
    ```

    Connect from anywhere using the standard Pinecone SDK or API.
  </Accordion>

  <Accordion title="Public access disabled">
    With public access disabled, you can only connect from within your VPC via private connectivity. You cannot use the Pinecone console for data plane operations (query, upsert, fetch), though control plane operations (create, delete, list indexes) still work.

    After deployment, the Pulumi stack outputs include the service name needed to create a private endpoint for your cloud provider. Use this service name to set up private connectivity:

    <Tabs>
      <Tab title="AWS">
        <Steps>
          <Step title="Create a VPC endpoint">
            Follow the instructions in the AWS documentation to [create a VPC endpoint](https://docs.aws.amazon.com/vpc/latest/privatelink/create-interface-endpoint.html#create-interface-endpoint-aws) for connecting to your indexes via AWS PrivateLink.

            For **Resource configurations**, use the VPC endpoint service name from the Pulumi stack outputs.
          </Step>

          <Step title="Select network settings">
            For **Network settings**, select the VPC for your BYOC deployment.
          </Step>

          <Step title="Enable DNS name">
            In **Additional settings**, select **Enable DNS name** to allow you to access your indexes using a DNS name.
          </Step>
        </Steps>
      </Tab>

      <Tab title="GCP">
        <Steps>
          <Step title="Create a private endpoint">
            Follow the instructions in the GCP documentation to [create a private endpoint](https://cloud.google.com/vpc/docs/configure-private-service-connect-services#create-endpoint) for connecting to your indexes via GCP Private Service Connect.

            * Set the **Target service** to the service attachment from the Pulumi stack outputs.
            * Copy the IP address of the private endpoint. You'll need it later.
          </Step>

          <Step title="Create a private DNS zone">
            Follow the instructions in the GCP documentation to [create a private DNS zone](https://cloud.google.com/dns/docs/zones#create-private-zone).

            * Set the **DNS name** to the following:

              ```
              <YOUR-BYOC-ENVIRONMENT>.byoc.pinecone.io
              ```
            * Select the same VPC network as the private endpoint.
          </Step>

          <Step title="Add a resource record set">
            Follow the instructions in the GCP documentation to [add a resource record set](https://cloud.google.com/dns/docs/records#add-rrset).

            * Set the **DNS name** to **\***.

            * Set the **Resource record type** to **A**.

            * Set the **Ipv4 Address** to the IP address of the private endpoint.
          </Step>
        </Steps>
      </Tab>

      <Tab title="Azure">
        <Steps>
          <Step title="Create a private endpoint">
            Follow the instructions in the Azure documentation to [create a private endpoint](https://learn.microsoft.com/en-us/azure/private-link/create-private-endpoint-portal) for connecting to your indexes via Azure Private Link.

            * Set the **Resource type** to `Microsoft.Network/privateLinkServices`.
            * Select the Private Link Service name from the Pulumi stack outputs.
            * Copy the IP address of the private endpoint. You'll need it later.
          </Step>

          <Step title="Create a private DNS zone">
            Follow the instructions in the Azure documentation to [create a private DNS zone](https://learn.microsoft.com/en-us/azure/dns/private-dns-getstarted-portal).

            * Set the **Name** to the following:

              ```
              <YOUR-BYOC-ENVIRONMENT>.byoc.pinecone.io
              ```
            * Link the zone to the VNet containing the private endpoint.
          </Step>

          <Step title="Add a wildcard A record">
            Follow the instructions in the Azure documentation to [add a record set](https://learn.microsoft.com/en-us/azure/dns/private-dns-getstarted-portal#create-an-additional-dns-record).

            * Set the **Name** to **\***.

            * Set the **Type** to **A**.

            * Set the **IP address** to the IP address of the private endpoint.
          </Step>
        </Steps>
      </Tab>
    </Tabs>

    Once configured, use the `private_host` URL from the Pinecone console or the [Describe an index](/reference/api/latest/control-plane/describe_index) API response. For example:

    ```
    https://my-index-abc123.svc.private.us-east-1.byoc.pinecone.io
    ```
  </Accordion>
</AccordionGroup>

## Manage BYOC

### Operations and upgrades

Pinecone uses a pull-based model for cluster operations:

1. When upgrades, scaling, or maintenance are needed, Pinecone queues operations in the control plane.
2. An agent running in your cluster (deployed automatically during setup) continuously pulls pending operations.
3. Operations execute locally within your cluster.
4. Status is reported back to Pinecone for monitoring.

This model ensures Pinecone never needs direct access to your infrastructure. All operations are stored as Kubernetes CRDs, providing a complete audit trail.

### Monitoring

You can monitor your BYOC deployment through multiple channels:

<AccordionGroup>
  <Accordion title="Pinecone console">
    View index metrics (read/write units, latency, storage) in the Pinecone console. Control plane operations and metrics work regardless of your network access mode.
  </Accordion>

  <Accordion title="Prometheus">
    To use Prometheus, configure your monitoring tool within your VPC to scrape metrics from the cluster. Your Prometheus instance must have network access to the BYOC VPC. The deployment output includes the metrics endpoint URL and port for configuration.
  </Accordion>

  <Accordion title="Audit logs">
    All cluster operations are persisted as Kubernetes CRDs for compliance and auditing:

    ```bash theme={null}
    kubectl get cluster-operations
    ```
  </Accordion>
</AccordionGroup>

### Cleanup

To destroy your BYOC deployment:

<Warning>
  Delete all BYOC indexes before destroying the cluster. Indexes cannot be properly terminated if the cluster is destroyed first.
</Warning>

```bash theme={null}
# 1. Delete all indexes via Pinecone API or console
# 2. Then destroy the infrastructure
pulumi destroy
```

If `deletion_protection` is enabled (the default), you must either disable it in `Pulumi.<stack>.yaml` and run `pulumi up`, or manually delete protected resources via the cloud console before running `pulumi destroy`:

* **AWS**: RDS instances and S3 buckets
* **GCP**: AlloyDB instances and GCS buckets
* **Azure**: PostgreSQL Flexible Server instances and Storage accounts

## Reference

### Troubleshooting

Common issues and how to resolve them:

<AccordionGroup>
  <Accordion title="Preflight check failures">
    The setup wizard validates cloud quotas before deployment. If checks fail:

    | Check                                | Resolution                                                                                                                                                                                                                          |
    | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | VPC / network quota                  | Request a limit increase via your cloud provider's quota console                                                                                                                                                                    |
    | Kubernetes cluster quota             | Request an EKS, GKE, or AKS cluster limit increase                                                                                                                                                                                  |
    | IP address quota                     | Release unused IPs or request a limit increase                                                                                                                                                                                      |
    | Instance / machine type availability | Verify the required type is available in your region                                                                                                                                                                                |
    | vCPU quota (Azure)                   | Request a "Total Regional vCPUs" increase via the Azure Portal (minimum 8 required)                                                                                                                                                 |
    | VM SKU availability (Azure)          | Verify `Standard_D4s_v5` and L-series SKUs are available in your region                                                                                                                                                             |
    | Resource providers (Azure)           | Register required providers: `Microsoft.Compute`, `Microsoft.ContainerService`, `Microsoft.DBforPostgreSQL`, `Microsoft.Storage`, `Microsoft.Network`, `Microsoft.KeyVault`, `Microsoft.ManagedIdentity`, `Microsoft.Authorization` |
    | Required APIs (GCP only)             | Enable Compute Engine, GKE, AlloyDB, Cloud Storage, and Cloud DNS                                                                                                                                                                   |
  </Accordion>

  <Accordion title="Deployment failures">
    If `pulumi up` fails partway through:

    ```bash theme={null}
    pulumi refresh  # Sync state with actual resources
    pulumi up       # Retry deployment
    ```
  </Accordion>

  <Accordion title="Cluster access issues">
    Ensure your cloud credentials match the account where the cluster is deployed:

    <Tabs>
      <Tab title="AWS">
        ```bash theme={null}
        aws sts get-caller-identity
        ```
      </Tab>

      <Tab title="GCP">
        ```bash theme={null}
        gcloud auth list
        gcloud config get-value project
        ```
      </Tab>

      <Tab title="Azure">
        ```bash theme={null}
        az account show
        ```
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="Index stuck in terminating state">
    If you destroyed the cluster before deleting indexes, indexes may be stuck in a "terminating" state. Contact [Pinecone support](https://app.pinecone.io/organizations/-/settings/support/ticket) for assistance.
  </Accordion>
</AccordionGroup>

For additional help, see the [GitHub Issues](https://github.com/pinecone-io/pulumi-pinecone-byoc/issues) for the deployment repository.

### Limitations

Some features available in the standard Pinecone service are not yet supported or have constraints in BYOC:

* Each organization can have up to 2 BYOC environments. To request an increase, contact [Pinecone support](https://app.pinecone.io/organizations/-/settings/support/ticket).
* [Integrated embedding and inference](/guides/index-data/indexing-overview#integrated-embedding), which relies on models hosted by Pinecone outside your cloud account.
* Reading and writing data from the index browser in the Pinecone console.
* Pinecone CLI data plane operations (queries, upserts, fetches). Control plane operations (create, list, delete indexes) work as expected.
* Imports from private cloud storage buckets, unless the bucket is in the same cloud account as your BYOC deployment.
* On-demand indexes (initial release supports DRN indexes only).

To [monitor with Prometheus](/guides/production/monitoring#monitor-with-prometheus), you must configure Prometheus within your VPC.

### FAQs

Answers to common questions about BYOC:

<AccordionGroup>
  <Accordion title="Does Pinecone have access to my cloud account?">
    No. BYOC is designed so Pinecone never needs direct access to your infrastructure. Specifically:

    * Pinecone does not need SSH, VPN, or inbound access to your cluster.
    * You control cloud account boundaries, networking, and Kubernetes access.
    * Operational changes run through explicit, software-mediated workflows.
    * You don't open inbound firewall ports for Pinecone operations.

    Operations are executed via a pull-based model where your cluster retrieves and runs operations locally. All communication is outbound from your cluster.
  </Accordion>

  <Accordion title="What data leaves my cluster?">
    **Does not leave your cloud account:**

    * Vectors, metadata, and index contents
    * Query and upsert payloads
    * Customer data

    **Can leave your cloud account:**

    * Operational metrics and traces (for example, CPU, memory, latency)
    * Cluster health and operation status

    Customer data is filtered out before transmission and never leaves your cloud account.
  </Accordion>

  <Accordion title="What is the difference between BYOC and Pinecone's standard service?">
    In the standard service, Pinecone manages all cloud resources and includes their cost in the service fee. In BYOC, you provision and pay for cloud resources directly through your own cloud account, providing greater control, data sovereignty, and access to available cloud credits or discounts.
  </Accordion>

  <Accordion title="How does authentication work?">
    You use API keys from the Pinecone console, just like with the standard Pinecone service. Authentication is handled by Pinecone's global control plane, and your data plane caches API keys locally. This means you manage users and API keys through the console as usual.
  </Accordion>

  <Accordion title="How is data secured in BYOC?">
    Data is stored and processed exclusively within your cloud account, with encryption at rest and in transit. You control at-rest encryption for the underlying resources (including KMS keys in your account) the same way you do for other infrastructure. Communication between the data plane and control plane is encrypted using TLS. Private connectivity (AWS PrivateLink, GCP Private Service Connect, or Azure Private Link) can be used for additional network isolation. For how this relates to hosted [CMEK](/guides/production/configure-cmek), see [Encryption and customer-managed keys](#encryption-and-customer-managed-keys).
  </Accordion>

  <Accordion title="Which cloud providers does BYOC support?">
    BYOC is available on AWS, GCP, and Azure.
  </Accordion>

  <Accordion title="What happens if I destroy the cluster before deleting indexes?">
    Indexes cannot be properly terminated if the cluster is destroyed first. Always delete indexes via the Pinecone API or console before running `pulumi destroy`.
  </Accordion>

  <Accordion title="What is the __SLI__ project in my organization?">
    Deploying a BYOC environment creates an internal project named `__SLI__` in your organization. This is used by Pinecone to enforce SLAs for your BYOC environment. Do not modify or delete this project.
  </Accordion>
</AccordionGroup>

### Pricing

BYOC pricing is based on provisioned resources (compute and storage) in your deployment, metered over time. Usage is measured by the Pinecone BYOC agent running in your cluster, which periodically reports the resources that are provisioned.

What you pay:

* Pinecone fees: Based on provisioned compute (vCPU and RAM) and storage (NVMe) resources
* Cloud provider fees: You pay your cloud provider directly for the underlying infrastructure (Kubernetes nodes, object storage, databases, networking, etc.)

Billing follows the agent heartbeat connection to Pinecone's control plane:

* When heartbeats are received, you are billed for the provisioned compute and storage the agent reports, even if the cluster is unhealthy.
* Short heartbeat interruptions (under 60 minutes) are treated as a grace period.
* If heartbeats are missing for more than 60 minutes, billing stops and the deployment is marked disconnected.

<Note>
  Billing is based on provisioned resources, not query volume. Resources that are running in your cluster are billed whether they are idle, actively processing queries, or experiencing errors.
</Note>


# Configure audit logs
Source: https://docs.pinecone.io/guides/production/configure-audit-logs

Enable Pinecone audit logging to an Amazon S3 bucket to track user, service account, and API actions for compliance, security review, and WORM retention.

This page describes how to configure audit logs in Pinecone. Audit logs provide a detailed record of user, service account, and API actions that occur on the management and [control plane](/guides/get-started/database-architecture#control-plane) within Pinecone. Pinecone supports Amazon S3 as a destination for audit logs.

<Note>
  To enable and manage audit logs, you must be an [organization owner](/guides/organizations/understanding-organizations#organization-roles). This feature is available only on [Enterprise plans](https://www.pinecone.io/pricing/).
</Note>

## Enable audit logs

1. Set up a [IAM policy and role in Amazon S3](/guides/operations/integrations/integrate-with-amazon-s3).
2. Go to [**Settings > Audit logs**](https://app.pinecone.io/organizations/-/settings/logging) in the Pinecone console.
3. Enter the **Role ARN** of the IAM role you created.
4. Enter the name of the Amazon S3 bucket you created.
   <Note>
     **Targeting a subdirectory:** You can write audit logs to a specific subdirectory by entering `bucket-name/subdirectory-path` in the bucket name field. For example: `my-bucket/pinecone-logs`. Make sure your [IAM policy is configured for subdirectory access](/guides/operations/integrations/integrate-with-amazon-s3#targeting-a-subdirectory-optional).
   </Note>
5. Click **Enable audit logging**.

Once you enable audit logs, Pinecone will start writing logs to the S3 bucket. In your bucket, you will also see a file named `audit-log-access-test`, which is a test file that Pinecone writes to verify that it has the necessary permissions to write logs to the bucket.

## Make your audit-log bucket immutable (recommended)

Because audit logs are written to an Amazon S3 bucket you control, you can enforce write-once-read-many (WORM) immutability so that log files cannot be modified or deleted — including by your own administrators — for a retention period you define. This is recommended for compliance use cases.

Enable [S3 Object Lock](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lock.html) in **compliance mode** with a retention period. Object Lock requires bucket versioning and, in general, must be enabled when the bucket is created — plan for it when you set up the [IAM policy and S3 bucket](/guides/operations/integrations/integrate-with-amazon-s3) above. Set the retention period to at least your required audit-log retention. Pinecone writes each log batch as a new, uniquely named file and does not modify or delete previously written logs.

<Warning>
  Compliance mode is intentionally irreversible: until a retention period expires, objects cannot be deleted and the period cannot be shortened — not even by the root account. Logs already written to the bucket are therefore retained for the full period even if you later disable or remove the audit log integration.
</Warning>

## View audit logs

Logs are written to the S3 bucket approximately every 30 minutes. Each log batch will be saved into its own file as a JSON blob, keyed by the time of the log to be written. Only logs since the integration was created and enabled will be saved.

For more information about the log schema and captured events, see [Understanding security - Audit logs](/guides/production/security-overview#audit-logs).

## Edit audit log integration details

You can edit the details of the audit log integration in the Pinecone console:

1. Go to [**Settings > Audit logs**](https://app.pinecone.io/organizations/-/settings/logging).
2. Enter the new **Role ARN** or **AWS Bucket**.
3. Click **Update settings**.

## Disable audit logs

If you disable audit logs, logs not yet saved will be lost. You can disable audit logs in the Pinecone console:

1. Go to [**Settings > Audit logs**](https://app.pinecone.io/organizations/-/settings/logging).
2. Click the toggle next to **Audit logs are active**.
3. Click **Confirm**.

## Remove audit log integration

If you remove the audit log integration, logs not yet saved will be lost. You can remove the audit log integration in the Pinecone console:

1. Go to [**Settings > Audit logs**](https://app.pinecone.io/organizations/-/settings/logging).
2. At the top of the page, click the **ellipsis (...) menu > Remove integration**.
3. Click **Remove integration**.


# Configure customer-managed encryption keys
Source: https://docs.pinecone.io/guides/production/configure-cmek

Set up customer-managed encryption keys (CMEK) with AWS KMS to encrypt Pinecone data with keys you control, using IAM roles and key policies.

<Note>
  This guide applies to **hosted** Pinecone projects where Pinecone manages your infrastructure. If you use [Bring your own cloud (BYOC)](/guides/production/bring-your-own-cloud), you encrypt data with **your** cloud provider KMS on resources in **your** account; follow the BYOC guide and [pulumi-pinecone-byoc](https://github.com/pinecone-io/pulumi-pinecone-byoc) instead of the console CMEK flow below.
</Note>

This page describes how to set up and use customer-managed encryption keys (CMEK) to secure data within a Pinecone project. CMEK allows you to encrypt your data using keys that you manage in your cloud provider's key management system (KMS). Pinecone supports CMEK using Amazon Web Services (AWS) KMS.

## Set up CMEK using AWS KMS

### Before you begin

The following steps assume you have:

* Access to the [AWS console](https://console.aws.amazon.com/console/home).
* A [Pinecone Enterprise plan](https://www.pinecone.io/pricing/).

### 1. Create a role

In the [AWS console](https://console.aws.amazon.com/console/home), create a role that Pinecone can use to access the AWS Key Management System (KMS) key. You can either grant Pinecone access to a key in your account, or if your customers provide their own keys, you can grant access to keys that are outside of your account.

<Tabs>
  <Tab title="Grant access to key in your account">
    1. Open the [Amazon Identity and Access Management (IAM) console](https://console.aws.amazon.com/iam/).

    2. In the navigation pane, click **Roles**.

    3. Click **Create role**.

    4. In the **Trusted entity type** section, select **Custom trust policy**.

    5. In the **Custom trust policy** section, enter one of the following JSON snippets.

       Pick a snippet based on whether you want to allow Pinecone to assume a role from all regions or from explicit regions. Add an optional external ID for additional security. If you use an external ID, you must provide it to Pinecone when [adding a CMEK key](#add-a-key).

       <AccordionGroup>
         <Accordion title="Explicit regions + external ID">
           ```jsonc JSON theme={null}
           {
               "Version": "2012-10-17",
               "Statement": [
                   {
                       "Sid": "AllowPineconeToAssumeIntoRoleFromExplicitRegionswithID",
                       "Effect": "Allow",
                       "Principal": {
                           "AWS": [
                               // Explicit role per Pinecone region. Replace XXXXXXXXXXXX with Pinecone's AWS account number.
                               "arn:aws:iam::XXXXXXXXXXXX:role/pinecone_cmek_access_us-east-1",
                               "arn:aws:iam::XXXXXXXXXXXX:role/pinecone_cmek_access_us-west-2",
                               "arn:aws:iam::XXXXXXXXXXXX:role/pinecone_cmek_access_eu-west-1",
                               "arn:aws:iam::XXXXXXXXXXXX:role/pinecone_cmek_access_eu-central-1",
                               "arn:aws:iam::XXXXXXXXXXXX:role/pinecone_cmek_access_ap-southeast-1"
                           ]
                       },
                       "Action": "sts:AssumeRole",
                       "Condition": {
                           "StringEquals": {
                               // Optional. Replace with a UUID v4 for additional security. If you use an external ID, you must provide it to Pinecone when adding an API key.
                               "sts:ExternalId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
                           }
                       }
                   }
               ]
           }
           ```
         </Accordion>

         <Accordion title="Explicit regions + no external ID">
           ```jsonc JSON theme={null}
           {
               "Version": "2012-10-17",
               "Statement": [
                   {
                       "Sid": "AllowPineconeToAssumeIntoRoleFromExplicitRegions",
                       "Effect": "Allow",
                       "Principal": {
                           "AWS": [
                               // Explicit role per Pinecone region. Replace XXXXXXXXXXXX with Pinecone's AWS account number.
                               "arn:aws:iam::XXXXXXXXXXXX:role/pinecone_cmek_access_us-east-1",
                               "arn:aws:iam::XXXXXXXXXXXX:role/pinecone_cmek_access_us-west-2",
                               "arn:aws:iam::XXXXXXXXXXXX:role/pinecone_cmek_access_eu-west-1",
                               "arn:aws:iam::XXXXXXXXXXXX:role/pinecone_cmek_access_eu-central-1",
                               "arn:aws:iam::XXXXXXXXXXXX:role/pinecone_cmek_access_ap-southeast-1"
                           ]
                       },
                       "Action": "sts:AssumeRole"
                   }
               ]
           }
           ```
         </Accordion>

         <Accordion title="All regions + external ID">
           ```jsonc JSON theme={null}
           {
               "Version": "2012-10-17",
               "Statement": [
                   {
                       "Sid": "AllowPineconeToAssumeIntoRoleFromAllRegions",
                       "Effect": "Allow",
                       "Principal": {
                           "AWS": "*"
                       },
                       "Action": "sts:AssumeRole",
                       "Condition": {
                           "StringEquals": {
                               // Optional. Replace with a UUID v4 for additional security. If you use an external ID, you must provide it to Pinecone when adding an API key.
                               "sts:ExternalId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
                           },
                           "StringLike": {
                               // Replace XXXXXXXXXXXX with Pinecone's AWS account number.
                               "aws:PrincipalArn": "arn:aws:iam::XXXXXXXXXXXX:role/pinecone_cmek_access_*"
                           }
                       }
                   }
               ]
           }
           ```
         </Accordion>
       </AccordionGroup>

       <Note>
         Replace `XXXXXXXXXXXX` with Pinecone's AWS account number, which can be found by going to [**Manage > CMEK**](https://app.pinecone.io/organizations/-/projects/-/cmek-encryption) in the Pinecone console and clicking **Add CMEK**.
       </Note>

    6. Click **Next**.

    7. Keep the default permissions as is and click **Next**.

    8. Enter a **Role name** and click **Create role**.

    9. Copy the **Role ARN** (e.g., `arn:aws:iam::XXXXXX:role/YYYYYY`). This will be used to [create a CMEK-enabled project](#3-create-a-cmek-enabled-project).
  </Tab>

  <Tab title="Grant access to keys outside your account">
    1. Open the [Amazon Identity and Access Management (IAM) console](https://console.aws.amazon.com/iam/).

    2. In the navigation pane, click **Roles**.

    3. Click **Create role**.

    4. In the **Trusted entity type** section, select **Custom trust policy**.

    5. In the **Custom trust policy** section, enter the following JSON:

       ```json JSON theme={null}
       {
           "Version": "2012-10-17",
           "Statement": [
               {
                   "Sid": "VisualEditor0",
                   "Effect": "Allow",
                   "Action": [
                       "kms:Decrypt",
                       "kms:Encrypt"
                   ],
                   "Resource": "arn:aws:kms:*:XXXXXX:key/*"
               }
           ]
       }
       ```

       * Replace `XXXXXX` with the account ID of the customer who owns the key.
       * Add a `Statement` array for each customer account ID.

    6. Click **Next**.

    7. Keep the default permissions as is and click **Next**.

    8. Enter a **Role name** and click **Create role**.

    9. Copy the **Role ARN** (e.g., `arn:aws:iam::XXXXXX:role/YYYYYY`). This will be used to [create a CMEK-enabled project](#3-create-a-cmek-enabled-project).
  </Tab>
</Tabs>

### 2. Create an AWS KMS key

In the [AWS console](https://console.aws.amazon.com/console/home), create the KMS key that Pinecone will use to encrypt your data:

1. Open the [Amazon Key Management Service (KMS) console](https://console.aws.amazon.com/kms/home).

2. In the navigation pane, click **Customer managed keys**.

3. Click **Create key**.

4. In the **Key type** section, select **Symmetric**.

5. In the **Key usage** section, select **Encrypt and decrypt**.

6. Under **Advanced options > Key material origin**, select **KMS**.

7. In the **Regionality** section, select **Single-Region key**.

   <Note>
     You can create a multi-regional key to safeguard against data loss in case of regional failure. However, Pinecone only accepts one Key ARN per project. If you set a multi-regional key and need to change the Key ARN to switch region, please [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) for help.
   </Note>

8. Click **Next**.

9. Enter an **Alias** and click **Next**.

10. Keep the default administrators as is and click **Next**.

11. Select the [role you created](#1-create-a-role) from the **Key users** list and click **Next**.

12. Click **Finish**.

13. Copy the **Key ARN** (e.g., `arn:aws:kms:us-east-1:XXXXXXX:key/YYYYYYY`). This will be used to [create a CMEK-enabled project](#create-a-cmek-enabled-project).

    <Note>
      **AWS KMS automatic key rotation is supported.** Pinecone references the Key ARN, not the underlying key material. As long as the Key ARN remains unchanged and accessible, you can perform key rotations inside AWS KMS without making any changes in Pinecone.
    </Note>

### 3. Create a CMEK-enabled project

Once your [role and key is configured](#set-up-cmek-using-aws-kms), you can create a CMEK-enabled project using the Pinecone console:

1. Go to [**Settings > Organization settings > Projects**](https://app.pinecone.io/organizations/-/settings/projects).

2. Click **+Create project**.

3. Enter a **Name**.

4. Select **Encrypt with Customer Managed Encryption Key**.

5. Click **Create project**.

6. Copy and save the generated API key in a secure place for future use.

   <Warning>
     You will not be able to see the API key again after you close the dialog.
   </Warning>

7. Click **Close**.

## Add a key

To start encrypting your data with a customer-managed key, you need to add the key to the [CMEK-enabled project](#3-create-a-cmek-enabled-project) using the Pinecone console:

1. Go to [**Manage > CMEK**](https://app.pinecone.io/organizations/-/projects/-/cmek-encryption) for the CMEK-enabled project.

2. Click **Add CMEK**.

   <Warning>
     You can only add one key per project, and you cannot change the key in Pinecone once it is set.
   </Warning>

3. Enter a **Key name**.

4. Enter the **Role ARN** for the [role you created](#1-create-a-role).

5. Enter a **Key ARN** for the [key you created](#2-create-a-aws-kms-key).

6. If you [created a role](#1-create-a-role) with an external ID, enter the **External ID**. If not, leave this field blank.

7. Click **Create key**.

## Delete a key

Before a key can be deleted from a project, all indexes in the project must be deleted. Then, you can delete the key using the Pinecone console:

1. Go to the [Manage > CMEK tab](https://app.pinecone.io/organizations/-/projects/-/cmek-encryption) for the project in which the key was created.
2. For the key you want to delete, click the **ellipsis (...) menu > Delete**.
3. Enter the key name to confirm deletion.
4. Click **Delete key**.

## Limitations

* CMEK can be enabled for serverless indexes in AWS regions only.
* [Backups](/guides/manage-data/back-up-an-index) are unavailable for indexes created in a CMEK-enabled project.
* You cannot change a key once it is set.
* You can add only one key per project.


# Configure Private Endpoints
Source: https://docs.pinecone.io/guides/production/configure-private-endpoints

Configure Pinecone Private Endpoints with AWS PrivateLink or Azure Private Link to keep index traffic off the public internet and secure VPCs.

This page describes how to create and use [Private Endpoints](/guides/production/security-overview#private-endpoints) to connect to Pinecone through AWS PrivateLink or Azure Private Link, keeping your traffic private from the public internet.

<a />

## Use Private Endpoints with Pinecone

### Before you begin

The following steps assume you have:

<Tabs>
  <Tab title="AWS">
    * Access to the [AWS console](https://console.aws.amazon.com/console/home).
    * [Created an Amazon VPC](https://docs.aws.amazon.com/vpc/latest/userguide/create-vpc.html#create-vpc-and-other-resources) in the same AWS [region](/guides/index-data/create-an-index#cloud-regions) as the index you want to connect to. You can optionally enable DNS hostnames and resolution, if you want your VPC to automatically discover the DNS CNAME for your PrivateLink and do not want to configure a CNAME.

      * To [configure the routing](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-vpc-interface-endpoint.html) yourself, use one of Pinecone's DNS entry for the corresponding region:

      | Index region                 | Pinecone DNS entry                     |
      | ---------------------------- | -------------------------------------- |
      | `us-east-1` (N. Virginia)    | `*.private.aped-4627-b74a.pinecone.io` |
      | `us-west-2` (Oregon)         | `*.private.apw5-4e34-81fa.pinecone.io` |
      | `eu-west-1` (Ireland)        | `*.private.apu-57e2-42f6.pinecone.io`  |
      | `eu-central-1` (Frankfurt)   | `*.private.apec-a2ee-38c6.pinecone.io` |
      | `ap-southeast-1` (Singapore) | `*.private.aps-d9bb-582b.pinecone.io`  |
  </Tab>

  <Tab title="Azure">
    * Access to the [Azure portal](https://portal.azure.com).
    * [Created an Azure VNet](https://learn.microsoft.com/en-us/azure/virtual-network/quick-create-portal) in the same [region](/guides/index-data/create-an-index#cloud-regions) as the index you want to connect to.
    * A subnet with **Private endpoint network policies** set to **Disabled**. This is required for Azure Private Endpoints.

      * DNS resolution for private endpoints requires a manual setup step after creating the endpoint (unlike AWS, where DNS can be auto-configured). See the [DNS setup note below](#1-create-a-private-endpoint-in-your-cloud-provider).

      | Index region         | Pinecone DNS entry                              |
      | -------------------- | ----------------------------------------------- |
      | `eastus2` (Virginia) | `*.private.eastus2-5e25.prod-azure.pinecone.io` |
  </Tab>
</Tabs>

* A [Pinecone Enterprise plan](https://www.pinecone.io/pricing/).
* [Created a serverless index](/guides/index-data/create-an-index#create-a-serverless-index) in the same [region](/guides/index-data/create-an-index#cloud-regions) as your VPC or VNet.

<Note>
  Private Endpoints are configured at the project-level and you can add up to 10 endpoints per project. If you have multiple projects in your organization, Private Endpoints need to be set up separately for each.
</Note>

<a />

### 1. Create a private endpoint in your cloud provider

<Tabs>
  <Tab title="AWS">
    In the [AWS console](https://console.aws.amazon.com/console/home):

    1. Open the [Amazon VPC console](https://console.aws.amazon.com/vpc/).

    2. In the navigation pane, click **Endpoint**.

    3. Click **Create endpoint**.

    4. For **Service category**, select **Other endpoint services**.

    5. In **Service settings**, enter the **Service name**, based on the region your Pinecone index is in:
       | Index region                 | Service name                                                   |
       | ---------------------------- | -------------------------------------------------------------- |
       | `us-east-1` (N. Virginia)    | `com.amazonaws.vpce.us-east-1.vpce-svc-05ef6f1f0b9130b54`      |
       | `us-west-2` (Oregon)         | `com.amazonaws.vpce.us-west-2.vpce-svc-04ecb9a0e0d5aab01`      |
       | `eu-west-1` (Ireland)        | `com.amazonaws.vpce.eu-west-1.vpce-svc-03c6b7e17ff02a70f`      |
       | `eu-central-1` (Frankfurt)   | `com.amazonaws.vpce.eu-central-1.vpce-svc-037997ff6b3d25e34`   |
       | `ap-southeast-1` (Singapore) | `com.amazonaws.vpce.ap-southeast-1.vpce-svc-0c12f00812e786068` |

    6. Click **Verify service**.

    7. Select the **VPC** to host the endpoint.

    8. (Optional) In **Additional settings**, **Enable DNS name**.
       The enables you to access our service with the DNS name we configure. An additional CNAME record is needed if you disable this option.

    9. Select the **Subnets** and **Subnet ID** for the endpoint.

    10. Select the **Security groups** to apply to the endpoint.

    11. Click **Create endpoint**.

    12. Copy the **VPC endpoint ID** (e.g., `vpce-XXXXXXX`).
        This will be used to [add a Private Endpoint in Pinecone](#2-add-a-private-endpoint-in-pinecone).
  </Tab>

  <Tab title="Azure">
    In the [Azure portal](https://portal.azure.com):

    1. Search for **Private Link** and select **Private Link Center**.

    2. In the navigation pane, click **Private endpoints**.

    3. Click **Create**.

    4. Select your **Subscription** and **Resource group**.

    5. Enter a **Name** for the private endpoint and select the **Region** matching your Pinecone index.

    6. Click **Next: Resource**.

    7. For **Connection method**, select **Connect to an Azure resource by resource ID or alias**.

    8. Enter the **Resource ID or alias** for Pinecone's Private Link Service, based on the region your Pinecone index is in:

       | Index region         | Private Link Service alias                                                       |
       | -------------------- | -------------------------------------------------------------------------------- |
       | `eastus2` (Virginia) | `pinecone.bdbc7759-0243-46c1-af51-794c4602745b.eastus2.azure.privatelinkservice` |

    9. Click **Next: Virtual Network**.

    10. Select the **Virtual network** and **Subnet** for the private endpoint.

    11. Click **Next: DNS**. Skip the DNS integration tab (you will configure DNS manually after setup).

    12. Click **Next: Tags**.

    13. Click **Review + create**, then **Create**.

    14. Once the private endpoint is created, open it and copy the **Resource ID** from the **Properties** tab (or the **Overview** tab — it's the `/subscriptions/…/privateEndpoints/<name>` ARM ID).
        This will be used to [add a Private Endpoint in Pinecone](#2-add-a-private-endpoint-in-pinecone).

    <Note>
      After creating the private endpoint, configure DNS so that `*.private.{subdomain}.pinecone.io` resolves to your private endpoint's IP address:

      1. Find your private endpoint's IP address: in the Azure portal, open your private endpoint, go to **Overview**, and note the **Private IP address** (e.g., `172.30.0.6`).
      2. Create an [Azure Private DNS Zone](https://learn.microsoft.com/en-us/azure/dns/private-dns-getstarted-portal) named `private.{subdomain}.pinecone.io` (e.g., `private.eastus2-5e25.prod-azure.pinecone.io`). You can find the `{subdomain}` in your index's host URL — it's the portion after `svc.` and before `.pinecone.io`.
      3. [Link the zone](https://learn.microsoft.com/en-us/azure/dns/private-dns-virtual-network-links) to the VNet where your private endpoint is created.
      4. Add a **wildcard A record** (`*`) pointing to your private endpoint's IP address.
    </Note>
  </Tab>
</Tabs>

### 2. Add a Private Endpoint in Pinecone

To add a Private Endpoint using the [Pinecone console](https://app.pinecone.io/organizations/-/projects):

1. Select your project.
2. Go to **Manage > Network**.
3. Click **Add a connection**.
4. Select your cloud provider and region.
   Only indexes in the selected region in this project will be affected.
5. Click **Next**.
6. Enter the endpoint ID you copied in the [section above](#1-create-a-private-endpoint-in-your-cloud-provider):
   * **AWS**: The VPC endpoint ID (e.g., `vpce-XXXXXXX`)
   * **Azure**: The private endpoint's ARM Resource ID (e.g., `/subscriptions/<sub-uuid>/resourceGroups/<rg>/providers/Microsoft.Network/privateEndpoints/<name>`)
7. Click **Next**.
8. (optional) To **enable private endpoint access only**, turn the toggle on.
   This can also be enabled later. For more information, see [Manage internet access to your project](#manage-internet-access-to-your-project).
9. Click **Finish setup**.

<Note>
  Private Endpoints only affect [data plane](/reference/api/latest/data-plane) access. [Control plane](/reference/api/latest/control-plane) access will continue over the public internet.
</Note>

## Read and write data

Once your private endpoint is configured, you can run data operations against an index as usual, but you must target the index using its private endpoint URL. The only difference in the URL is that `.svc.` is changed to `.svc.private.`.

You can get the private endpoint URL for an index from the Pinecone console or API.

<Tabs>
  <Tab title="Console">
    To get the private endpoint URL for an index from the Pinecone console:

    1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects).
    2. Select the project containing the index.
    3. Select the index.
    4. Copy the URL under **PRIVATE ENDPOINT**.
  </Tab>

  <Tab title="API">
    To get the private endpoint URL for an index from the API, use the [`describe_index`](/reference/api/latest/control-plane/describe_index) operation, which returns the private endpoint URL as the `private_host` value:

    <CodeGroup>
      ```JavaScript JavaScript theme={null}
      import { Pinecone } from '@pinecone-database/pinecone';

      const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' });

      await pc.describeIndex('docs-example');
      ```

      ```go Go theme={null}
      package main

      import (
          "context"
          "encoding/json"
          "fmt"
          "log"

          "github.com/pinecone-io/go-pinecone/v4/pinecone"
      )

      func prettifyStruct(obj interface{}) string {
          bytes, _ := json.MarshalIndent(obj, "", "  ")
          return string(bytes)
      }

      func main() {
          ctx := context.Background()

          pc, err := pinecone.NewClient(pinecone.NewClientParams{
              ApiKey: "YOUR_API_KEY",
          })
          if err != nil {
              log.Fatalf("Failed to create Client: %v", err)
          }

          idx, err := pc.DescribeIndex(ctx, "docs-example")
          if err != nil {
              log.Fatalf("Failed to describe index \"%v\": %v", idx.Name, err)
          } else {
              fmt.Printf("index: %v\n", prettifyStruct(idx))
          }
      }
      ```

      ```bash curl theme={null}
      PINECONE_API_KEY="YOUR_API_KEY"

      curl -i -X GET "https://api.pinecone.io/indexes/docs-example" \
          -H "Api-Key: YOUR_API_KEY" \
          -H "X-Pinecone-Api-Version: 2025-10"
      ```
    </CodeGroup>

    The response includes the private endpoint URL as the `private_host` value:

    <CodeGroup>
      ```json JavaScript {6} theme={null}
      {
        name: 'docs-example',
        dimension: 1536,
        metric: 'cosine',
        host: 'docs-example-jl7boae.svc.aped-4627-b74a.pinecone.io',
        privateHost: 'docs-example-jl7boae.svc.private.aped-4627-b74a.pinecone.io',
        deletionProtection: 'disabled',
        tags: { environment: 'production' },
        embed: undefined,
        spec: {
          byoc: undefined,
          pod: undefined,
          serverless: { cloud: 'aws', region: 'us-east-1' }
        },
        status: { ready: true, state: 'Ready' },
        vectorType: 'dense'
      }
      ```

      ```go Go {5} theme={null}
      index: {
        "name": "docs-example",
        "dimension": 1536,
        "host": "docs-example-jl7boae.svc.aped-4627-b74a.pinecone.io",
        "private_host": "docs-example-jl7boae.svc.private.aped-4627-b74a.pinecone.io",
        "metric": "cosine",
        "deletion_protection": "disabled",
        "spec": {
          "serverless": {
            "cloud": "aws",
            "region": "us-east-1"
          }
        },
        "status": {
          "ready": true,
          "state": "Ready"
        },
        "tags": {
          "environment": "production"
        }
      }
      ```

      ```json curl {12} theme={null}
      {
        "id": "025117b3-e683-423c-b2d1-6d30fbe5027f",
        "vector_type": "dense",
        "name": "docs-example",
        "metric": "cosine",
        "dimension": 1536,
        "status": {
          "ready": true,
          "state": "Ready"
        },
        "host": "docs-example-jl7boae.svc.aped-4627-b74a.pinecone.io",
        "private_host": "docs-example-jl7boae.svc.private.aped-4627-b74a.pinecone.io",
        "spec": {
          "serverless": {
            "region": "us-east-1",
            "cloud": "aws"
          }
        },
        "deletion_protection": "disabled",
        "tags": {
          "environment": "production"
        }
      ```
    </CodeGroup>
  </Tab>
</Tabs>

<Note>
  If you run data operations against an index from outside the Private Endpoint, you will get an `Unauthorized` response.
</Note>

## Manage internet access to your project

Once your Private Endpoint is configured, you can turn off internet access to your project. To enable private endpoint access only:

1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects).
2. Select your project.
3. Go to **Network > Access**.
4. Turn the **Private endpoint access only** toggle on.
   This will turn off internet access to the project. This can be turned off at any point.

   <Warning>
     This access control is set at the *project-level* and can unintentionally affect Pinecone indexes that communicate via the internet in the same project. Only indexes communicating through Private Endpoints will continue to work.
   </Warning>

## Manage Private Endpoints

In addition to [creating Private Endpoints](#2-add-a-private-endpoint-in-pinecone), you can also:

* [View Private Endpoints](#view-private-endpoints)
* [Delete a Private Endpoint](#delete-a-private-endpoint)

### View Private Endpoints

To view Private Endpoints using the [Pinecone console](https://app.pinecone.io/organizations/-/projects):

1. Select your project.
2. Go to **Manage > Network**.
   A list of Private Endpoints displays with the associated endpoint ID and cloud provider.

### Delete a Private Endpoint

To delete a Private Endpoint using the [Pinecone console](https://app.pinecone.io/organizations/-/projects):

1. Select your project.
2. Go to **Manage > Network**.
3. For the Private Endpoint you want to delete, click the *...* (Actions) icon.
4. Click **Delete**.
5. Enter the endpoint name.
6. Click **Delete Endpoint**.


# Configure SSO with Okta
Source: https://docs.pinecone.io/guides/production/configure-single-sign-on/okta

Set up SAML single sign-on between Pinecone and Okta so your organization members can log in with corporate credentials.

This page describes how to set up Pinecone with Okta as the single sign-on (SSO) provider. These instructions can be adapted for any provider with SAML 2.0 support.

<Note>SSO is available on Standard and Enterprise plans.</Note>

## Before you begin

This page assumes you have the following:

* Access to your organization's [Pinecone console](https://login.pinecone.io) as an [organization owner](/guides/organizations/understanding-organizations#organization-roles).
* Access to your organization's [Okta Admin console](https://login.okta.com/).

## 1. Start SSO setup in Pinecone

First, start setting up SSO in Pinecone. In this step, you'll capture a couple values necessary for configuring Okta in [Step 2](#2-create-an-app-integration-in-okta).

1. In the Pinecone console, go to [**Settings > Access > Identity provider**](https://app.pinecone.io/organizations/-/settings/access/identity-provider).
2. In the **Single sign-on** section, click **Enable SSO**.
3. In the **Setup SSO** dialog, copy the **Entity ID** and the **Assertion Consumer Service (ACS) URL**. You'll need these values in [Step 2](#2-create-an-app-integration-in-okta).
4. Click **Next**.

Keep this window or browser tab open. You'll come back to it in [Step 4](#4-complete-sso-setup-in-pinecone).

## 2. Create an app integration in Okta

In [Okta](https://login.okta.com/), follow these steps to create and configure a Pinecone app integration:

1. If you're not already on the Okta Admin console, navigate there by clicking the **Admin** button.

2. Navigate to **Applications > Applications**.

3. Click **Create App Integration**.

4. Select **SAML 2.0**.

5. Click **Next**.

6. Enter the **General Settings**:

   * **App name**: `Pinecone`
   * **App logo**: (optional)
   * **App visibility**: Set according to your organization's needs.

7. Click **Next**.

8. For **SAML Settings**, enter values you copied in [Step 1](#1-start-sso-setup-in-pinecone):

   * **Single sign-on URL**: Your **Assertion Consumer Service (ACS) URL**
   * **Audience URI (SP Entity ID)**: Your **Entity ID**
   * **Name ID format**: `EmailAddress`
   * **Application username**: `Okta username`
   * **Update application username on**: `Create and update`

9. In the **Attribute Statements (SAML)** section, create the following attribute:

   * **Name**: `email`
   * **Value**: `user.email`

   <Note>
     In newer versions of Okta, attribute statements are configured on the app's **Sign On** tab after the app is created, rather than in the app creation wizard. If you don't see the **Attribute Statements (SAML)** section here, finish creating the app, then add the attribute from **Applications > Pinecone > Sign On**, expanding **Show legacy configuration** if needed.
   </Note>

10. Click **Next**.

11. Click **Finish**.

## 3. Get the sign on URL and certificate from Okta

Next, in Okta, get the URL and certificate for the Pinecone application you just created. You'll use these in [Step 4](#4-complete-sso-setup-in-pinecone).

1. In the Okta Admin console, navigate to **Applications > Pinecone > Sign On**. If you're continuing from the previous step, you should already be on the right page.
2. In the **SAML 2.0** section, expand **More details**.
3. Copy the **Sign on URL**.
4. Download the **Signing Certificate**.

   <Warning>
     Download the certificate, don't copy it. The downloaded version contains necessary `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----` lines.
   </Warning>

## 4. Complete SSO setup in Pinecone

In the browser tab or window you kept open in [Step 1](#1-start-sso-setup-in-pinecone), complete the SSO setup in Pinecone:

1. In the **SSO Setup** window, enter the following values:

   * **Login URL**: The URL copied in [Step 3](#3-get-the-sign-on-url-and-certificate-from-okta).
   * **Email domain**: Your company's email domain. To target multiple domains, enter each domain separated by a comma.
   * **Certificate**: The contents of the certificate file you copied in [Step 3](#3-get-the-sign-on-url-and-certificate-from-okta).

     <Warning>
       When pasting the certificate, be sure to include the `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----` lines.
     </Warning>

2. Choose whether or not to **Enforce SSO for all users**.

   * If enabled, all members of your organization must use SSO to log in to Pinecone.
   * If disabled, members can choose to log in with SSO or with their Pinecone credentials.

3. Click **Next**.

4. Select a **Default role** for all users who log in with SSO. You can change user roles later.

   <Note>
     The **Default role** does not apply if you enable [SAML role management](/guides/production/configure-single-sign-on/okta-role-management). In that mode, every user's organization and project roles come entirely from your identity provider's SAML attributes.
   </Note>

   <Warning>
     When users first log in via SSO, they receive the default SSO role regardless of their previous role. Subsequent SSO logins do not change the role. If the default is **Member** or **Manager**, existing owners will lose owner access on their first SSO login.

     To prevent losing access to organization management features:

     * **Sole owner**: Temporarily set the default to **Owner**, log in via SSO to retain owner access, then change the default back to **Member**. After changing it back, check your organization's user list to verify no one else logged in via SSO while the default was **Owner**—if they did, adjust their roles accordingly.
     * **Multiple owners**: Keep at least one owner signed in via email while others log in via SSO. That owner can restore roles as needed, then log in via SSO last.

     If all owners lose access, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).
   </Warning>

Okta is now ready to be used for single sign-on. Follow the [Okta docs](https://help.okta.com/en-us/content/topics/users-groups-profiles/usgp-main.htm) to learn how to add users and groups.

## Manage roles automatically

Optionally, you can have Pinecone assign organization and project roles automatically from your identity provider on each login, instead of managing them manually. For more information, see [Manage roles with Okta](/guides/production/configure-single-sign-on/okta-role-management).


# Manage roles with Okta
Source: https://docs.pinecone.io/guides/production/configure-single-sign-on/okta-role-management

Automatically assign Pinecone organization and project roles from SAML attributes with Okta.

Instead of managing roles manually in Pinecone, you can have Pinecone automatically assign organization and project roles from your identity provider (IdP) on each login. This page continues [Configure SSO with Okta](/guides/production/configure-single-sign-on/okta) and shows how to set up SAML role management with Okta. These instructions can be adapted for any provider with SAML 2.0 support.

<Note>SAML role management is available on the Enterprise plan and builds on SAML SSO. Before you begin, [configure SSO with Okta](/guides/production/configure-single-sign-on/okta) and enforce SSO for your organization.</Note>

## How it works

When SAML role management is enabled, Pinecone reconciles each user's roles on every SSO login:

* Pinecone reads the roles your IdP sends in the SAML `roles` attribute.
* It replaces the user's organization and project roles with *exactly* the roles in that attribute. Roles for projects not included in the attribute are removed, and values that don't match a known role are ignored.
* Because roles come entirely from your IdP, while this mode is enabled you can no longer invite members or edit roles in the Pinecone console or through the Admin API, and the SSO **Default role** is not applied.
* To revoke a member's access, remove their roles in your IdP. At their next sign-in, Pinecone clears all of their organization and project roles and blocks the login. Active members are re-authenticated at least every 24 hours, so the change applies within a day.

<Note>
  Because SSO is enforced, deactivating or removing a member in your IdP blocks them from signing in to Pinecone right away, so their access ends immediately. Their role assignments stay in Pinecone until their next sign-in—which a removed member never reaches—so the assignments remain but grant no access on their own. To clear them, or to have Pinecone remove members automatically, use [SCIM provisioning](/guides/production/configure-single-sign-on/okta-scim-provisioning). You can also switch to **Manage roles in Pinecone** to remove the member manually, then switch back.
</Note>

To avoid losing access, configure and verify the `roles` attribute in Okta *before* you enable SAML role management in Pinecone. The steps below are in that order.

<Warning>
  Enabling SAML role management does not validate your IdP configuration, so a user missing an organization role can be locked out on their next login. Before you enable it, verify the `roles` attribute for a current owner (see [Step 2](#2-verify-the-roles-in-the-saml-assertion)).
</Warning>

## Role attribute values

Pinecone reads roles from the `roles` attribute. Each value uses one of the following formats:

* Organization role: `pinecone:<OrgRole>`
* Project role: `pinecone:project:<projectID>:<ProjectRole>`

`<projectID>` is the project's unique ID. To find it, go to the project list in the [Pinecone console](https://app.pinecone.io/organizations/-/projects). For more information, see [Project IDs](/guides/projects/understanding-projects#project-ids).

A user can hold multiple roles by sending multiple values in the `roles` attribute.

### Organization roles

For details on what each [organization role](/guides/organizations/understanding-organizations#organization-roles) grants, see [Understanding organizations](/guides/organizations/understanding-organizations#organization-roles).

| Organization role    | Attribute value            |
| :------------------- | :------------------------- |
| Organization owner   | `pinecone:OrgOwner`        |
| Organization manager | `pinecone:OrgManager`      |
| Organization member  | `pinecone:OrgMember`       |
| Billing admin        | `pinecone:OrgBillingAdmin` |

### Project roles

For details on what each [project role](/guides/projects/understanding-projects#project-roles) grants, see [Understanding projects](/guides/projects/understanding-projects#project-roles).

| Project role         | Attribute value                                   |
| :------------------- | :------------------------------------------------ |
| Project owner        | `pinecone:project:<projectID>:ProjectOwner`       |
| Project manager      | `pinecone:project:<projectID>:ProjectManager`     |
| Project member       | `pinecone:project:<projectID>:ProjectMember`      |
| Control plane editor | `pinecone:project:<projectID>:ControlPlaneEditor` |
| Control plane viewer | `pinecone:project:<projectID>:ControlPlaneViewer` |
| Data plane editor    | `pinecone:project:<projectID>:DataPlaneEditor`    |
| Data plane viewer    | `pinecone:project:<projectID>:DataPlaneViewer`    |

For example, to make a user an organization manager who is also a project owner on one project, send these two values in the `roles` attribute:

```text theme={null}
pinecone:OrgManager
pinecone:project:a2f7dddb-1597-4eff-9f71-535fde243f58:ProjectOwner
```

## 1. Send roles from Okta

Configure Okta to send each user's roles in a SAML attribute named `roles`, where each value is one of the [role attribute values](#role-attribute-values) above. You can populate that attribute in a few ways; choose whichever fits how you already manage users in Okta.

<Note>
  In newer versions of Okta, attribute and group statements are configured on the app's **Sign On** tab after the app is created, rather than in the app creation wizard. If you don't see the **Attribute Statements (SAML)** section, expand **Show legacy configuration** within it.
</Note>

### Option A: From a user profile attribute

Use this option to set roles directly on each user's Okta profile.

1. In Okta, go to **Directory > Profile Editor** and edit the **Okta** user profile.
2. Add an attribute named `pineconeRoles` with data type **string array**.
3. For each user, set `pineconeRoles` to their `pinecone:*` values (directly, or through a profile mapping).
4. In **Applications > Pinecone > Sign On**, add an **Attribute Statement**:

   * **Name**: `roles`
   * **Name format**: `Unspecified`
   * **Value**: `user.pineconeRoles`

### Option B: From group membership

Use this option to assign roles by adding users to Okta groups.

1. In Okta, create a group for each Pinecone role you want to assign, naming each group exactly as the role's attribute value (for example, `pinecone:OrgOwner` or `pinecone:project:<projectID>:ProjectManager`), and add the appropriate users to each group.
2. In **Applications > Pinecone > Sign On**, send those group names in the `roles` attribute using either:

   * A **Group Attribute Statement** with **Name** `roles`, **Name format** `Unspecified`, and **Filter** **Starts with** `pinecone:`.
   * Or an **Attribute Statement** with **Name** `roles` and the expression `user.getGroups({'group.profile.name': 'pinecone:', 'operator': 'STARTS_WITH'}).![profile.name]`.

<Note>
  The `user.getGroups(...).![profile.name]` expression is for an app-level attribute statement on the **Sign On** tab, and it returns every matching group, so no `limit` argument is required. (Only the `Groups.startsWith`, `Groups.endsWith`, and `Groups.contains` functions require a `limit`.) If you configure this claim on a custom authorization server instead, use the `.![name]` projection.
</Note>

Any other approach works as well, as long as the `roles` attribute resolves to the role attribute values.

## 2. Verify the roles in the SAML assertion

Before you hand role management to Okta, confirm the `roles` attribute contains what you expect.

1. In **Applications > Pinecone > Sign On**, click **Preview the SAML Assertion**.
2. Select a user who should be an organization owner and generate the preview.
3. Confirm the assertion includes a `roles` attribute containing `pinecone:OrgOwner` (and any project roles you assigned).

<Warning>
  If no current organization owner's preview includes `pinecone:OrgOwner`, fix your Okta configuration before continuing. Enabling SAML role management without a provisioned owner can lock your organization out of role management. If the `roles` attribute is empty or missing, re-check your attribute statement expression and projection before continuing, as a malformed expression returns no roles rather than an error.
</Warning>

## 3. Enable SAML role management in Pinecone

<Note>You must be an [organization owner](/guides/organizations/understanding-organizations#organization-roles) on the Enterprise plan, and SSO must be enforced for your organization.</Note>

1. In the Pinecone console, go to [**Settings > Access > Identity provider**](https://app.pinecone.io/organizations/-/settings/access/identity-provider).
2. Confirm that single sign-on shows the **Enforced** status. If it does not, edit your SSO configuration to enforce SSO before continuing.
3. In the **User management** section, select **Manage roles with SAML attributes**.
4. In the **Enable SAML role management** dialog, review the **Before you enable** prerequisites, then click **Enable SAML role management**.

Role assignment now comes entirely from your IdP. Roles update at the member's next SSO login. Since SAML sessions re-authenticate at least every 24 hours, an active user's role changes apply within 24 hours. Default role assignments configured during SSO setup no longer apply.

To stop syncing roles from your IdP, return to **Settings > Access > Identity provider** and select **Manage roles in Pinecone**. Existing roles are preserved, and you can edit them again in the console.


# SCIM provisioning with Okta
Source: https://docs.pinecone.io/guides/production/configure-single-sign-on/okta-scim-provisioning

Automatically provision members and roles from Okta to Pinecone over SCIM.

Instead of managing members and roles manually in Pinecone, you can have your identity provider (IdP) provision them automatically over SCIM. This page continues [Configure SSO with Okta](/guides/production/configure-single-sign-on/okta) and shows how to set up SCIM provisioning with Okta. These instructions can be adapted for any provider with SCIM 2.0 support.

<Note>SCIM provisioning is available on the Enterprise plan and builds on SAML SSO. Before you begin, [configure SSO with Okta](/guides/production/configure-single-sign-on/okta) and enforce SSO for your organization.</Note>

## How it works

When SCIM provisioning is enabled, your IdP manages organization membership and roles in Pinecone in near real time:

* As members are added, updated, or removed in Okta, those changes sync to Pinecone over SCIM in near real time, not just at login.
* Okta connects to a SCIM endpoint that Pinecone provides, authenticating with a bearer token you generate in the Pinecone console.
* Pinecone reads each member's roles from the SCIM `roles` attribute and sets their organization and project roles to *exactly* those values. Values that don't match a known role are ignored.
* While SCIM is enabled, SCIM is the source of truth for roles: Pinecone no longer applies the roles in a member's SAML login assertion, even though members still sign in through SAML SSO.
* Deactivating or removing a member in Okta removes them from the organization, and clearing a member's roles revokes their access.
* Because membership and roles come entirely from your IdP, while SCIM is enabled you can no longer invite members or edit roles in the Pinecone console or through the Admin API.

<Note>
  Provisioning changes in Okta are typically reflected in Pinecone within a few minutes, but can take up to 30 minutes to fully propagate.
</Note>

<Note>
  SCIM provisioning assigns roles from user attributes only. SCIM group push is not supported. This is similar to [SAML role management](/guides/production/configure-single-sign-on/okta-role-management), except roles are provisioned continuously rather than at each login, and member deprovisioning is handled automatically.
</Note>

<Warning>
  Before you enable SCIM, provision at least one current [organization owner](/guides/organizations/understanding-organizations#organization-roles) with the `pinecone:OrgOwner` role. Pinecone blocks enabling SCIM until a current owner has been provisioned as an owner, so that handing role management to your IdP cannot lock you out.
</Warning>

<Warning>
  SCIM provisioning is not compatible with members who belong to more than one SSO-connected Pinecone organization. If a member is part of multiple SSO-connected organizations, do not provision them through SCIM; manage their roles manually instead.
</Warning>

## Role attribute values

Pinecone reads roles from the `roles` attribute. Each value uses one of the following formats:

* Organization role: `pinecone:<OrgRole>`
* Project role: `pinecone:project:<projectID>:<ProjectRole>`

`<projectID>` is the project's unique ID. To find it, go to the project list in the [Pinecone console](https://app.pinecone.io/organizations/-/projects). For more information, see [Project IDs](/guides/projects/understanding-projects#project-ids).

A user can hold multiple roles by sending multiple values in the `roles` attribute.

### Organization roles

For details on what each [organization role](/guides/organizations/understanding-organizations#organization-roles) grants, see [Understanding organizations](/guides/organizations/understanding-organizations#organization-roles).

| Organization role    | Attribute value            |
| :------------------- | :------------------------- |
| Organization owner   | `pinecone:OrgOwner`        |
| Organization manager | `pinecone:OrgManager`      |
| Organization member  | `pinecone:OrgMember`       |
| Billing admin        | `pinecone:OrgBillingAdmin` |

### Project roles

For details on what each [project role](/guides/projects/understanding-projects#project-roles) grants, see [Understanding projects](/guides/projects/understanding-projects#project-roles).

| Project role         | Attribute value                                   |
| :------------------- | :------------------------------------------------ |
| Project owner        | `pinecone:project:<projectID>:ProjectOwner`       |
| Project manager      | `pinecone:project:<projectID>:ProjectManager`     |
| Project member       | `pinecone:project:<projectID>:ProjectMember`      |
| Control plane editor | `pinecone:project:<projectID>:ControlPlaneEditor` |
| Control plane viewer | `pinecone:project:<projectID>:ControlPlaneViewer` |
| Data plane editor    | `pinecone:project:<projectID>:DataPlaneEditor`    |
| Data plane viewer    | `pinecone:project:<projectID>:DataPlaneViewer`    |

For example, to make a user an organization manager who is also a project owner on one project, send these two values in the `roles` attribute:

```text theme={null}
pinecone:OrgManager
pinecone:project:a2f7dddb-1597-4eff-9f71-535fde243f58:ProjectOwner
```

## 1. Start SCIM setup in Pinecone

<Note>You must be an [organization owner](/guides/organizations/understanding-organizations#organization-roles) on the Enterprise plan, and SSO must be enforced for your organization.</Note>

1. In the Pinecone console, go to [**Settings > Access > Identity provider**](https://app.pinecone.io/organizations/-/settings/access/identity-provider).
2. Confirm that single sign-on shows the **Enforced** status. If it does not, edit your SSO configuration to enforce SSO before continuing.
3. In the **User management** section, select **Manage roles with SCIM provisioning**.
4. In the **Set up SCIM provisioning** dialog, review the instructions and click **Get started**.

## 2. Generate a SCIM token

1. Choose the token's permissions and expiry. By default the token grants all user permissions and expires in 90 days; you can also choose **Token never expires**.
2. Click **Generate token**.
3. Copy the **bearer token**. The **SCIM endpoint** is shown on the next screen of the dialog. You'll add both to Okta in [Step 3](#3-connect-okta-to-the-scim-endpoint).

<Warning>
  The bearer token is shown only once. Copy it before closing the dialog. You can have at most two active tokens per organization; rotate or revoke them later from the **Manage** dialog.
</Warning>

## 3. Connect Okta to the SCIM endpoint

1. In [Okta](https://login.okta.com/), navigate to **Applications > Pinecone > General**.

2. In the **App Settings** section, click **Edit**, set **Provisioning** to **SCIM**, and click **Save**.

3. Open the **Provisioning** tab and click **Configure API Integration**.

4. Select **Enable API Integration** and enter the following:

   * **SCIM connector base URL**: The **SCIM endpoint** you copied in [Step 2](#2-generate-a-scim-token).
   * **Unique identifier field for users**: `userName`.
   * **Authentication Mode**: `HTTP Header`.
   * **Authorization**: The **bearer token** you copied in [Step 2](#2-generate-a-scim-token).

5. Click **Test API Credentials** to verify the connection, then click **Save**.

6. Under **Provisioning > To App**, click **Edit** and enable **Create Users**, **Update User Attributes**, and **Deactivate Users**.

<Note>
  If the **Provisioning** tab or **Configure API Integration** button does not appear, SCIM provisioning is not enabled on the app.

  If **Test API Credentials** fails, re-copy the SCIM endpoint and bearer token from Pinecone, and confirm the token has not expired or been revoked.
</Note>

## 4. Send role values to Pinecone

Okta does not send a member's Pinecone roles by default. You define one app attribute per role you want to assign, then map a value to it for the right members. Pinecone reads only each value, so the same approach scales to as many roles as you need.

1. In Okta, go to **Directory > Profile Editor** and open the **Pinecone** app profile.

2. For each role you want to assign, click **Add Attribute** and configure:

   * **Data type**: `string`
   * **External name**: `roles.^[type=='<label>'].value`, where `<label>` is any unique label for the role (for example, `orgOwner` or `projManager`). Pinecone reads only the value, so the label is only used to keep attributes distinct in Okta.
   * **External namespace**: `urn:ietf:params:scim:schemas:core:2.0:User`

3. Go to **Provisioning > To App > Pinecone Attribute Mappings** (or **Mappings** in the Profile Editor) and map each attribute to the role value for the members who should hold it. Set the mapping to apply **on create and update**. Source the value however you manage users, for example:

   * From a custom user profile attribute that holds the `pinecone:*` value.
   * From group membership with an expression such as `isMemberOfGroupName('Pinecone Owners') ? 'pinecone:OrgOwner' : ''`.

4. Click **Preview** for a representative user and confirm the `roles` attribute resolves to the expected `pinecone:*` values (including `pinecone:OrgOwner` for a current owner).

For example, an organization manager who is also a project owner on one project needs two attributes: one mapped to `pinecone:OrgManager` and one mapped to `pinecone:project:<projectID>:ProjectOwner`. Project values include the project's [unique ID](/guides/projects/understanding-projects#project-ids), not its name.

<Note>
  Send roles in the user's `roles` attribute. SCIM group push is not supported.
</Note>

## 5. Provision members and verify

1. Assign your members to the Pinecone app in Okta so it pushes them over SCIM. For members who were already assigned, use **Provisioning > To App > Force Sync** or **Apply updates now** so their attributes resync.
2. Confirm the members and roles arrived. In Okta, check **Reports > System Log** (or the app's provisioning activity) for SCIM errors if members don't appear.
3. Verify that at least one current Pinecone [organization owner](/guides/organizations/understanding-organizations#organization-roles) was provisioned with `pinecone:OrgOwner`.

## 6. Enable SCIM in Pinecone

1. Back in the Pinecone **Set up SCIM provisioning** dialog, click **Enable SCIM**. Pinecone verifies that an organization owner has been provisioned with `pinecone:OrgOwner` before activating.
2. If Pinecone blocks activation because no owner is provisioned, return to Okta, assign `pinecone:OrgOwner` to a current owner (see [Step 4](#4-send-role-values-to-pinecone)), let it sync, and click **Enable SCIM** again.

Once enabled, your IdP is the source of truth for membership and roles. Members and their roles sync automatically as you provision them in Okta.

To rotate or revoke tokens or view the SCIM endpoint, select **Manage** next to the SCIM option. To stop provisioning, select **Manage roles in Pinecone** (or **Disable SCIM** from the **Manage** dialog), which revokes all SCIM tokens and reverts to manual role management. Existing role assignments are preserved until you change them.


# Data deletion on Pinecone
Source: https://docs.pinecone.io/guides/production/data-deletion

Learn how Pinecone permanently deletes customer data, including soft deletion, the 90-day retention window, and secure erasure of records and indexes.

Pinecone follows a secure process to ensure that customer data is permanently deleted from our system. This page gives an overview of the process.

As defined in the [Master Subscription Agreement](https://www.pinecone.io/legal/master-subscription-agreement/), customer data is data that you provide to Pinecone through the services of the Pinecone system, or such data provided on your behalf by connected systems. This includes objects such as [records](/guides/get-started/concepts#record), [indexes](/guides/get-started/concepts#index), [backups](/guides/get-started/concepts#backup-or-collection), [projects](/guides/get-started/concepts#project), [API keys](/guides/get-started/concepts#api-key), [users](/guides/get-started/concepts#user), [assistants](/guides/get-started/concepts#pinecone-assistant), and [organizations](/guides/get-started/concepts#organization).

## Deletion request

The deletion of customer data begins when you initiate a deletion request through the Pinecone API, console, or a connected service. A deletion request can delete a single resource, such as a record, or can delete a resource and all its dependent resources, such as an index and all its records.

Deletion of your customer data also occurs automatically when you end your relationship with Pinecone. If your account is [deactivated for continued non-payment](/guides/organizations/manage-billing/non-payment-account-deactivation), account data is retained for 30 days before permanent deletion.

## Soft deletion

After you initiate a deletion request, Pinecone marks the data for deletion. The data is not immediately removed from the system. Instead, Pinecone retains the data for a maximum of 90 days. During this period, the data is not accessible to you or any other user.

## Permanent deletion

Before the end of the 90-day retention window, Pinecone permanently deletes the data from its system. Once the data is permanently deleted, it is no longer recoverable.

<Note>
  Pinecone creates an [audit log](/guides/production/security-overview#audit-logs) of user, service account, and API events. Events are captured within two hours of occurrence and are retained for 90 days, after which they are permanently deleted.
</Note>

## See also

* [Delete records](/guides/manage-data/delete-data)
* [Delete an index](/guides/manage-data/manage-indexes#delete-an-index)
* [Delete a project](/guides/projects/manage-projects#delete-a-project)
* [Delete an API key](/guides/projects/manage-api-keys#delete-an-api-key)
* [Delete a user](/guides/projects/manage-project-members#remove-members)
* [Delete an organization](/troubleshooting/delete-your-organization)
* [Master Subscription Agreement](https://www.pinecone.io/legal/master-subscription-agreement/)


# Error handling
Source: https://docs.pinecone.io/guides/production/error-handling

Handle Pinecone API errors with retry logic, exponential backoff, and best practices for 4xx client errors, 5xx server errors, and rate limit responses.

## Understand error types

Pinecone uses [conventional HTTP response codes](/reference/api/errors) to indicate the success or failure of API requests:

* **2xx codes** indicate success
* **4xx codes** indicate client errors (issues with your request)
* **5xx codes** indicate server errors (issues with Pinecone's servers)

### Client errors (4xx)

Client errors indicate problems with your request. These errors typically require changes to your code or configuration:

* **400 - Invalid Argument**: Your request contains invalid parameters. Check your request format and parameters.
* **401 - Unauthenticated**: Your API key is missing or invalid. Verify your [API key](/guides/projects/manage-api-keys).
* **402 - Payment Required**: Your account has a payment issue or may be deactivated for non-payment. Check your billing status in the [console](https://app.pinecone.io) and see [Account deactivation for non-payment](/guides/organizations/manage-billing/non-payment-account-deactivation).
* **403 - Forbidden**: You've exceeded a [quota](/reference/api/database-limits#object-limits) or hit [deletion protection](/guides/manage-data/manage-indexes#configure-deletion-protection).
* **404 - Not Found**: The requested resource doesn't exist. Verify the resource name and that it hasn't been deleted.
* **409 - Already Exists**: You're trying to create a resource that already exists.
* **429 - Too Many Requests**: You're being [rate-limited](/reference/api/database-limits#rate-limits). Implement [backoff and retry logic](#implement-retry-logic).

### Server errors (5xx)

Server errors indicate temporary issues with Pinecone's infrastructure:

* **500 - Unknown**: An internal server error occurred.
* **502 - Bad Gateway**: The API gateway received an invalid response from a backend service.
* **503 - Unavailable**: The service is currently unavailable.
* **504 - Gateway Timeout**: The API gateway did not receive a timely response from the backend server. This can occur due to slow requests or backend processing delays.

**Best practice for 5xx errors**: [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). These errors are typically transient.

## Capture errors

Each SDK provides error handling mechanisms specific to the language:

### Python SDK

The Python SDK raises exceptions that you can catch and handle:

```python theme={null}
from pinecone import Pinecone
from pinecone.exceptions import PineconeException

pc = Pinecone(api_key="YOUR_API_KEY")
index = pc.Index("your-index")

try:
    index.upsert(
        vectors=[
            {"id": "vec1", "values": [0.1, 0.2, 0.3]}
        ]
    )
except PineconeException as e:
    # Handle Pinecone-specific errors
    print(f"Pinecone error: {e}")
except Exception as e:
    # Handle other errors
    print(f"Unexpected error: {e}")
```

See the [Python SDK documentation](https://sdk.pinecone.io/python/) for more details on exception handling.

### Node.js SDK

The Node.js SDK uses standard JavaScript error handling:

```javascript theme={null}
const { Pinecone } = require('@pinecone-database/pinecone');

const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' });

try {
  const index = pc.index('your-index');
  await index.upsert([
    { id: 'vec1', values: [0.1, 0.2, 0.3] }
  ]);
} catch (error) {
  console.error('Error upserting data:', error);
  // Handle the error appropriately
}
```

See the [Node.js SDK documentation](https://sdk.pinecone.io/typescript/) for more information.

### Other SDKs

For SDK-specific error handling patterns, see the documentation for your language:

* [Go SDK](/reference/sdks/go/overview)
* [Java SDK](/reference/sdks/java/overview)

## Implement retry logic

For transient errors (5xx codes and 429 rate limiting), implement retry logic. Start with basic retries for simple use cases, or use exponential backoff for production systems.

### Basic retry logic

For simple use cases, start with a basic retry loop with fixed delays:

```python theme={null}
import time
from pinecone.exceptions import PineconeException

def simple_retry(func, max_retries=3, delay=2):
    """
    Retry a function with a fixed delay between attempts.

    Args:
        func: Function to retry
        max_retries: Maximum number of retry attempts
        delay: Delay in seconds between retries
    """
    for attempt in range(max_retries):
        try:
            return func()
        except PineconeException as e:
            if attempt == max_retries - 1:
                raise  # Last attempt, re-raise the exception

            print(f"Attempt {attempt + 1} failed, retrying in {delay}s...")
            time.sleep(delay)

# Usage
try:
    simple_retry(lambda: index.upsert(vectors))
except Exception as e:
    print(f"Failed after {max_retries} attempts: {e}")
```

This basic approach works well for occasional transient errors, but for production systems with higher traffic, use exponential backoff instead.

### Exponential backoff

Exponential backoff progressively increases the wait time between retries to avoid overwhelming the service:

```python theme={null}
import time
import random

def exponential_backoff_retry(func, max_retries=5, base_delay=1, max_delay=60):
    """
    Retry a function with exponential backoff.

    Args:
        func: Function to retry
        max_retries: Maximum number of retry attempts
        base_delay: Initial delay in seconds
        max_delay: Maximum delay between retries
    """
    for attempt in range(max_retries):
        try:
            return func()
        except PineconeException as e:
            if attempt == max_retries - 1:
                raise  # Last attempt, re-raise the exception

            # Get status code if available
            status_code = getattr(e, 'status', None)

            # Only retry on 5xx errors or 429 (rate limiting)
            if status_code and (status_code >= 500 or status_code == 429):
                # Calculate delay with exponential backoff and jitter
                delay = min(base_delay * (2 ** attempt), max_delay)
                jitter = random.uniform(0, delay * 0.1)  # Add 10% jitter
                wait_time = delay + jitter

                print(f"Retry attempt {attempt + 1}/{max_retries} after {wait_time:.2f}s")
                time.sleep(wait_time)
            else:
                # Don't retry client errors (4xx except 429)
                raise

# Usage
try:
    exponential_backoff_retry(lambda: index.upsert(vectors))
except Exception as e:
    print(f"Failed after retries: {e}")
```

### Go SDK

The Go SDK has built-in retries with exponential backoff. Set a `RetryPolicy` on the client and it applies to both the REST (control/data/inference) and gRPC (data plane) clients. Retries cover 429 and transient 5xx / gRPC `UNAVAILABLE` errors; other 4xx errors are never retried.

```go theme={null}
package main

import (
	"os"

	"github.com/pinecone-io/go-pinecone/v6/pinecone"
)

func main() {
	pc, err := pinecone.NewClient(pinecone.NewClientParams{
		ApiKey:      os.Getenv("PINECONE_API_KEY"),
		RetryPolicy: pinecone.DefaultRetryPolicy(), // 3 retries, 500ms base, 30s cap, 2x backoff
	})
	if err != nil {
		panic(err)
	}
	_ = pc
}
```

To customize the behavior, construct a `RetryPolicy` with your own `MaxRetries`, `BaseDelay`, `MaxDelay`, and `BackoffMultiplier`. See the [Go SDK documentation](/reference/sdks/go/overview) for details.

### Key retry principles

1. **Add jitter**: Random variation in retry timing helps avoid thundering herd problems.
2. **Set max retries**: Prevent infinite retry loops.
3. **Cap delay time**: Don't wait indefinitely between retries.
4. **Don't retry client errors**: 4xx errors (except 429) won't resolve with retries.
5. **Log retry attempts**: Track retry behavior for monitoring and debugging.

## Handle rate limits (429)

When you receive a 429 error, you're being rate-limited. See [Rate limits](/reference/api/database-limits#rate-limits) for current limits.

Rate limits help protect your applications and maintain the health of the serverless infrastructure. **Most limits can be adjusted upon request**—if you need higher limits to scale, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) with details about your use case.

<Note>
  Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide.
</Note>

**Best practices**:

* Implement exponential backoff as described above.
* Proactively [monitor request metrics](/guides/production/monitoring) and reduce the request rate if you're approaching limits.
* Use [batching](/guides/index-data/upsert-data#upsert-in-batches) to reduce the number of requests.
* For high-throughput needs, see [Increase throughput](/guides/optimize/increase-throughput).

## Getting support

If you've implemented error handling and retry logic but continue to experience issues:

1. Review [How to work with Support](/troubleshooting/how-to-work-with-support) for best practices.
2. Gather the following information:
   * Index name and project name
   * Error messages and stack traces
   * Timestamp of errors
   * Request/response examples (without sensitive data)
   * Whether the issue is reproducible
3. [Contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

Ensure your [plan tier](https://www.pinecone.io/pricing/) provides the support SLA you need for production workloads.

## See also

* [API error codes](/reference/api/errors)
* [Database limits](/reference/api/database-limits)
* [Assistant limits](/reference/api/assistant/assistant-limits)
* [Monitoring](/guides/production/monitoring)
* [Production checklist](/guides/production/production-checklist)


# Manage roles and access
Source: https://docs.pinecone.io/guides/production/manage-rbac

Assign and manage roles for users, service accounts, and API keys using the Pinecone console or the Admin API.

Pinecone uses [role-based access controls (RBAC)](/guides/production/security-overview#role-based-access-controls-rbac) to manage access to resources. Users, service accounts, and API keys are all *principals*, and a principal's access is determined by the *roles* assigned to it for a *resource* (an organization or a project).

This page shows how to assign and manage roles in the [Pinecone console](https://app.pinecone.io) and programmatically with the Admin API.

<Note>
  For the roles available at each scope and the permissions they grant, see [Organization roles](/guides/organizations/understanding-organizations#organization-roles) and [Project roles](/guides/projects/understanding-projects#project-roles).
</Note>

## Common role assignments

A user must have an organization role to belong to the organization, and gains access to a project through one or more project roles. A principal's effective permissions are the union of all the roles it holds, so you can combine roles to grant exactly the access a user needs.

The following table maps common scenarios to the roles to assign:

| Scenario                                                           | Organization role | Project role(s)                                                                       |
| :----------------------------------------------------------------- | :---------------- | :------------------------------------------------------------------------------------ |
| Administer the organization and every project                      | `OrgOwner`        | None (inherits owner access to all projects)                                          |
| Create and manage projects, but not billing or members             | `OrgManager`      | Assign per project as needed                                                          |
| Manage billing, subscriptions, and usage                           | `OrgBillingAdmin` | None                                                                                  |
| Lead a single project, including its members and API keys          | `OrgMember`       | `ProjectOwner`                                                                        |
| Build and query in a project, without managing members or API keys | `OrgMember`       | `ProjectManager`                                                                      |
| Read and write index data only                                     | `OrgMember`       | `ProjectMember` and `DataPlaneEditor`                                                 |
| Read-only access to a project's resources and data                 | `OrgMember`       | `ProjectMember`, `ControlPlaneViewer`, and `DataPlaneViewer`                          |
| Work across two projects at different access levels                | `OrgMember`       | `ProjectManager` on one project and `ProjectMember` with `DataPlaneViewer` on another |

<Note>
  Assigning an organization role adds the user to the organization; assigning a project role grants access to that specific project. To assign these roles in the console, see [Manage organization members](/guides/organizations/manage-organization-members) and [Manage project members](/guides/projects/manage-project-members).
</Note>

### Invite a developer to a project

Invite a user as an organization member and grant them the `ProjectManager` role so they can build and query in a single project without managing its members or API keys.

In the console, add the user from [Manage project members](/guides/projects/manage-project-members) and select the **Project manager** role. With the Admin API, include both roles in the `role_bindings` array when you invite the user:

```bash curl theme={null}
PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

curl "https://api.pinecone.io/admin/invites" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Pinecone-Api-Version: 2026-04" \
  -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
  -d '{
    "email": "developer@example.com",
    "role_bindings": [
      {
        "resource_type": "organization",
        "role": "OrgMember"
      },
      {
        "resource_type": "project",
        "resource_id": "a2f7dddb-1597-4eff-9f71-535fde243f58",
        "role": "ProjectManager"
      }
    ]
  }'
```

For more information, see [Assign roles when creating a principal](#assign-roles-when-creating-a-principal).

### Grant an existing user read-only data access

To give a user who is already in your organization read-only access to a project's data, assign the `ProjectMember` role for baseline project access and the `DataPlaneViewer` role for read-only data. Each role binding is a separate request.

First, add the user to the project with the `ProjectMember` role:

```bash curl theme={null}
PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

curl "https://api.pinecone.io/admin/role-bindings" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Pinecone-Api-Version: 2026-04" \
  -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
  -d '{
    "principal_type": "user",
    "principal_id": "c7b1f0a2-3d4e-5f6a-7b8c-9d0e1f2a3b4c",
    "resource_type": "project",
    "resource_id": "a2f7dddb-1597-4eff-9f71-535fde243f58",
    "role": "ProjectMember"
  }'
```

Then, grant read-only data access with the `DataPlaneViewer` role:

```bash curl theme={null}
PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

curl "https://api.pinecone.io/admin/role-bindings" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Pinecone-Api-Version: 2026-04" \
  -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
  -d '{
    "principal_type": "user",
    "principal_id": "c7b1f0a2-3d4e-5f6a-7b8c-9d0e1f2a3b4c",
    "resource_type": "project",
    "resource_id": "a2f7dddb-1597-4eff-9f71-535fde243f58",
    "role": "DataPlaneViewer"
  }'
```

### Extend a user's access with an additional role

Because effective permissions are the union of all roles, you can broaden access by adding another role rather than replacing the existing one. The user from the previous example holds `ProjectMember` and `DataPlaneViewer`; add `ControlPlaneViewer` to also allow read-only access to the project's indexes, assistants, backups, and collections:

```bash curl theme={null}
PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

curl "https://api.pinecone.io/admin/role-bindings" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Pinecone-Api-Version: 2026-04" \
  -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
  -d '{
    "principal_type": "user",
    "principal_id": "c7b1f0a2-3d4e-5f6a-7b8c-9d0e1f2a3b4c",
    "resource_type": "project",
    "resource_id": "a2f7dddb-1597-4eff-9f71-535fde243f58",
    "role": "ControlPlaneViewer"
  }'
```

The user now holds `ProjectMember`, `DataPlaneViewer`, and `ControlPlaneViewer` on the project, giving read-only access to all of its resources and data. For more information, see [Create a role binding](#create-a-role-binding).

## Manage roles in the console

You can assign and change roles when you manage principals in the console:

* [Manage organization members](/guides/organizations/manage-organization-members)
* [Manage project members](/guides/projects/manage-project-members)
* [Manage organization service accounts](/guides/organizations/manage-service-accounts) and [project service accounts](/guides/projects/manage-service-accounts)
* [Manage API keys](/guides/projects/manage-api-keys)

## Manage roles with the Admin API

The Admin API represents each role assignment as a *role binding* that grants one role to one principal for one resource scope. You can assign roles when you create a principal, or manage role bindings directly after creation.

<Note>
  An [access token](/guides/organizations/manage-service-accounts#retrieve-an-access-token) must be provided to authenticate with the Admin API.
</Note>

### Assign roles when creating a principal

When you invite a user or create a service account, grant roles with the `role_bindings` field. Set `resource_type` to `organization` or `project`; for `project` scope, include the project's `resource_id`.

Invite a user as an organization member with a project role:

```bash curl theme={null}
PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

curl "https://api.pinecone.io/admin/invites" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Pinecone-Api-Version: 2026-04" \
  -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
  -d '{
    "email": "newhire@example.com",
    "role_bindings": [
      {
        "resource_type": "organization",
        "role": "OrgMember"
      },
      {
        "resource_type": "project",
        "resource_id": "a2f7dddb-1597-4eff-9f71-535fde243f58",
        "role": "ProjectMember"
      }
    ]
  }'
```

Create a service account with an access role:

```bash curl theme={null}
PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

curl "https://api.pinecone.io/admin/service-accounts" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Pinecone-Api-Version: 2026-04" \
  -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
  -d '{
    "name": "ci-prod",
    "role_bindings": [
      {
        "resource_type": "project",
        "resource_id": "a2f7dddb-1597-4eff-9f71-535fde243f58",
        "role": "DataPlaneEditor"
      }
    ]
  }'
```

For API keys, assign [project roles](/guides/projects/understanding-projects#project-roles) with the `roles` field instead. For more information, see [Manage API keys](/guides/projects/manage-api-keys).

### Create a role binding

To grant a role to an existing principal, create a role binding:

```bash curl theme={null}
PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

curl "https://api.pinecone.io/admin/role-bindings" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Pinecone-Api-Version: 2026-04" \
  -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
  -d '{
    "principal_type": "service_account",
    "principal_id": "f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
    "resource_type": "project",
    "resource_id": "a2f7dddb-1597-4eff-9f71-535fde243f58",
    "role": "DataPlaneEditor"
  }'
```

For more information, see [Create a role binding](/reference/api/2026-04/admin/create_role_binding).

### List role bindings

Role bindings are not included in the responses for users, invites, or service accounts. To list the roles assigned to a principal, filter by `principal_type` and `principal_id`:

```bash curl theme={null}
PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

curl "https://api.pinecone.io/admin/role-bindings?principal_type=service_account&principal_id=f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c" \
  -H "Accept: application/json" \
  -H "X-Pinecone-Api-Version: 2026-04" \
  -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN"
```

For more information, see [List role bindings](/reference/api/2026-04/admin/list_role_bindings) and [Fetch a role binding](/reference/api/2026-04/admin/fetch_role_binding).

### Delete a role binding

To revoke a role, delete its role binding:

```bash curl theme={null}
PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

curl -X DELETE "https://api.pinecone.io/admin/role-bindings/9a8e3528-b9c0-4358-84ce-84c28e91b566" \
  -H "Accept: application/json" \
  -H "X-Pinecone-Api-Version: 2026-04" \
  -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN"
```

<Warning>
  You cannot delete the last `OrgOwner` role binding for an organization. An organization must always have at least one owner.
</Warning>

For more information, see [Delete a role binding](/reference/api/2026-04/admin/delete_role_binding).


# Monitor performance
Source: https://docs.pinecone.io/guides/production/monitoring

Monitor Pinecone index performance metrics (query latency, throughput, and errors) in the Pinecone console or via Prometheus and Datadog.

Pinecone generates time-series performance metrics for each Pinecone index. You can monitor these metrics directly in the Pinecone console or with tools like Prometheus or Datadog.

## Monitor in the Pinecone Console

To view performance metrics in the Pinecone console:

1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects).
2. Select the project containing the index you want to monitor.
3. Go to **Database > Indexes**.
4. Select the index.
5. Go to the **Metrics** tab.

## Monitor with Datadog

To monitor Pinecone with Datadog, use Datadog's [Pinecone integration](/integrations/datadog).

<Note>
  This feature is available on the [Builder, Standard, and Enterprise plans](https://www.pinecone.io/pricing/).
</Note>

## Monitor with Prometheus

<Note>
  This feature is available on the [Builder, Standard, and Enterprise plans](https://www.pinecone.io/pricing/). When using [Bring Your Own Cloud](/guides/production/bring-your-own-cloud), you must configure Prometheus monitoring within your VPC.
</Note>

To monitor all serverless indexes in a project, insert the following snippet into the [`scrape_configs`](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#scrape_config) section of your `prometheus.yml` file and update it with values for your Prometheus integration:

<Note>
  This method uses [HTTP service discovery](https://prometheus.io/docs/prometheus/latest/http_sd/) to automatically discover and target all serverless indexes across all regions in a project.
</Note>

```YAML theme={null}
global:
  scrape_interval: 15s

scrape_configs:
  - job_name: 'pinecone-serverless-metrics'
    http_sd_configs:
      - url: https://api.pinecone.io/prometheus/projects/PROJECT_ID/metrics/discovery
        refresh_interval: 1m
        authorization:
          type: Bearer
          credentials: API_KEY
    authorization:
      type: Bearer
      credentials: API_KEY
```

* Replace `PROJECT_ID` with the unique ID of the project you want to monitor. You can [find the project ID](/guides/projects/understanding-projects#project-ids) in the Pinecone console.

* Replace both instances of `API_KEY` with an API key for the project you want to monitor. The first instance is for service discovery, and the second instance is for the discovered targets. If necessary, you can [create an new API key](/guides/projects/manage-api-keys) in the Pinecone console.

For more configuration details, see the [Prometheus docs](https://prometheus.io/docs/prometheus/latest/configuration/configuration/).

### Available metrics

The following metrics are available when you integrate Pinecone with Prometheus:

<div>
  | Name                                         | Type    | Description                                                                                                                    |
  | :------------------------------------------- | :------ | :----------------------------------------------------------------------------------------------------------------------------- |
  | `pinecone_db_record_total`                   | gauge   | The total number of records in the index.                                                                                      |
  | `pinecone_db_storage_size_bytes`             | gauge   | The total size of the index in bytes.                                                                                          |
  | `pinecone_db_op_upsert_count`                | counter | The number of [upsert](/guides/index-data/upsert-data) requests.                                                               |
  | `pinecone_db_op_upsert_duration_sum`         | counter | The total time taken processing [upsert](/guides/index-data/upsert-data) requests in milliseconds.                             |
  | `pinecone_db_op_query_count`                 | counter | The number of [query](/guides/search/search-overview) requests.                                                                |
  | `pinecone_db_op_query_duration_sum`          | counter | The total time taken processing [query](/guides/search/search-overview) requests in milliseconds.                              |
  | `pinecone_db_op_fetch_count`                 | counter | The number of [fetch](/guides/manage-data/fetch-data) requests.                                                                |
  | `pinecone_db_op_fetch_duration_sum`          | counter | The total time taken processing [fetch](/guides/manage-data/fetch-data) requests in milliseconds.                              |
  | `pinecone_db_op_update_count`                | counter | The number of [update](/guides/manage-data/update-data) requests.                                                              |
  | `pinecone_db_op_update_duration_sum`         | counter | The total time taken processing [update](/guides/manage-data/update-data) requests in milliseconds.                            |
  | `pinecone_db_op_delete_count`                | counter | The number of [delete](/guides/manage-data/delete-data) requests.                                                              |
  | `pinecone_db_op_delete_duration_sum`         | counter | The total time taken processing [delete](/guides/manage-data/delete-data) requests in milliseconds.                            |
  | `pinecone_db_op_list_count`                  | counter | The number of [list](/guides/manage-data/list-record-ids) requests.                                                            |
  | `pinecone_db_op_list_duration_sum`           | counter | The total time taken processing [list](/guides/manage-data/list-record-ids) requests in milliseconds.                          |
  | `pinecone_db_write_unit_count`               | counter | The total number of [write units](/guides/manage-cost/understanding-cost#write-units) consumed by an index.                    |
  | `pinecone_db_read_unit_count`                | counter | The total number of [read units](/guides/manage-cost/understanding-cost#read-units) consumed by an index.                      |
  | `pinecone_db_scheduled_backup_failure_total` | counter | The number of terminal failures for [scheduled backup](/guides/manage-data/back-up-an-index) create operations.                |
  | `pinecone_db_drn_cpu_usage_percent`          | gauge   | The CPU usage percentage for a [dedicated read node](/guides/index-data/dedicated-read-nodes) shard, averaged across replicas. |
</div>

### Metric labels

Each metric contains the following labels:

| Label           | Description                                                        |
| :-------------- | :----------------------------------------------------------------- |
| `index_name`    | Name of the index to which the metric applies.                     |
| `cloud`         | Cloud where the index is deployed: `aws`, `gcp`, or `azure`.       |
| `region`        | Region where the index is deployed.                                |
| `capacity_mode` | Type of index: `serverless` or `byoc`.                             |
| `instance`      | Server instance (only available for counter metrics).              |
| `shard_id`      | Shard identifier (only available for dedicated read node metrics). |

### Example queries

Return the total number of records per index:

```shell theme={null}
sum by (index_name) (pinecone_db_record_total)
```

Return the total number of records in Pinecone index `docs-example`:

```shell theme={null}
pinecone_db_record_total{index_name="docs-example"}
```

For each index, return the total number of upsert requests per second:

```shell theme={null}
sum by (index_name) (rate(pinecone_db_op_upsert_count[5m]))
```

Return the average processing time in milliseconds for upsert requests per index:

```shell theme={null}
(sum by (index_name) (rate(pinecone_db_op_upsert_duration_sum[1m])))/(sum by (index_name) (rate(pinecone_db_op_upsert_count[1m])))
```

For each index, return the total number of read units consumed per second:

```shell theme={null}
sum by (index_name) (rate(pinecone_db_read_unit_count[5m]))
```

Return the total write units consumed per second for the Pinecone index `docs-example`:

```shell theme={null}
sum (rate(pinecone_db_write_unit_count{index_name="docs-example"}[5m]))
```

Return the CPU usage percentage per shard for Pinecone index `docs-example`:

```shell theme={null}
avg by (shard_id) (pinecone_db_drn_cpu_usage_percent{index_name="docs-example"})
```


# Production checklist
Source: https://docs.pinecone.io/guides/production/production-checklist

Prepare Pinecone indexes for production with best practices for project structure, security, scaling, API keys, and reliability across your workloads.

This page provides recommendations and best practices for preparing your Pinecone indexes for production, anticipating production issues, and enabling reliability and growth.

## Prepare your project structure

One of the first steps towards building a production-ready Pinecone index is configuring your project correctly.

* Consider [creating a separate project](/guides/projects/create-a-project) for your development and production indexes, to allow for testing changes to your index before deploying them to production.
* Ensure that you have properly [configured user access](/guides/projects/understanding-projects#project-roles) to the Pinecone console, so that only those users who need to access the production index can do so.
* Ensure that you have properly configured access through the API by [managing API keys](/guides/projects/manage-api-keys) and using API key permissions.

Consider how best to [manage the API keys](/guides/projects/manage-api-keys) associated with your production project. In order to [make calls to the Pinecone API](/guides/get-started/quickstart), you must provide a valid API key for the relevant Pinecone project.

## Enforce security

Use Pinecone's [security features](/guides/production/security-overview) to protect your production data:

* Data security
  * Private endpoints
  * Customer-managed encryption keys (CMEK) for hosted projects; for BYOC, use KMS on your own resources ([Bring your own cloud](/guides/production/bring-your-own-cloud))
* Authorization
  * API keys
  * Role-based access control (RBAC)
  * Organization single sign-on (SSO)
* Audit logs
* Bring your own cloud

## Design your indexes for scale

Follow these best practices when designing and populating your indexes:

* **Data ingestion**: For large datasets (10M+ records), [import from object storage](/guides/index-data/import-data) for the most efficient and cost-effective ingestion. For ongoing ingestion, [upsert in batches](/guides/index-data/upsert-data#upsert-in-batches) to optimize speed and efficiency. See the [data ingestion overview](/guides/index-data/data-ingestion-overview) for details.
* **Dimensionality**: Consider the dimensionality of your vectors. Higher dimensions can offer more accuracy but require more resources.
* **Data modeling**: Use [structured IDs](/guides/index-data/data-modeling#use-structured-ids) (e.g., `document_id#chunk_number`) for efficient operations. Design [metadata](/guides/index-data/data-modeling#include-metadata) to support filtering, linking related chunks, and traceability. See the [data modeling guide](/guides/index-data/data-modeling) for details.
* **Namespaces**: When indexing, try to [use namespaces to keep your data among tenants separate](/guides/index-data/implement-multitenancy), and do not use multiple indexes for this purpose. Namespaces are more efficient and more affordable in the long run.

## Understand database limits

Architect your application to work within Pinecone's [database limits](/reference/api/database-limits):

* **Rate limits**: Serverless indexes have per-second operation limits for queries, upserts, updates, and deletes. [Implement error handling with exponential backoff](/guides/production/error-handling) to handle rate limit errors gracefully.
* **Size limits**: Be aware of constraints on vector dimensionality, metadata size per record, record ID length, maximum `top_k` values, and query result sizes. Design your [data model](/guides/index-data/data-modeling) accordingly.
* **Index limits**: Plan for index capacity based on your [plan tier](https://www.pinecone.io/pricing/). Use [namespaces](/guides/index-data/implement-multitenancy) to partition data within indexes rather than creating multiple indexes.
* **Plan limits**: The Starter and Builder plans have monthly read/write unit limits. Upgrade to Standard or Enterprise for unlimited read/write units and higher throughput needs.

<Note>
  Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide.
</Note>

## Test your query results

Before you move your index to production, make sure that your index is returning accurate results in the context of your application by [identifying the appropriate metrics](https://www.pinecone.io/learn/offline-evaluation/) for evaluating your results.

## Optimize performance

Before serving production workloads, optimize your Pinecone implementation:

* **Increase search relevance**: Use techniques like reranking, metadata filtering, hybrid search, and chunking strategies to improve result quality. See [increase search relevance](/guides/optimize/increase-relevance) for details.
* **Increase throughput**: Import from object storage, upsert in batches, use parallel operations, and leverage Python SDK optimizations like gRPC. See [increase throughput](/guides/optimize/increase-throughput) for details.
* **Decrease latency**: Use namespaces, filter by metadata, target indexes by host, reuse connections, and deploy in the same cloud region as your index. See [decrease latency](/guides/optimize/decrease-latency) for details.
* **Save on costs**: Prefer bulk import for large initial loads, use namespaces for multitenancy, and avoid unnecessary data in query responses. See [save on costs](/guides/optimize/save-on-costs) for details.

## Backup up your indexes

In order to enable long-term retention, compliance archiving, and deployment of new indexes, consider backing up your production indexes by [creating a backup or collection](/guides/manage-data/back-up-an-index).

## Implement error handling

Prepare your application to handle errors gracefully:

* Implement [error handling and retry logic](/guides/production/error-handling) with exponential backoff
* Handle different error types appropriately (4xx vs 5xx)
* Monitor error rates and set up alerts
* Check [status.pinecone.io](https://status.pinecone.io) before escalating issues

## Configure monitoring

Prepare to [monitor the production performance and availability of your indexes](/guides/production/monitoring).

## Configure CI/CD

Use [Pinecone in CI/CD](/guides/production/automated-testing) to safely test changes before deploying them to production.

## Know how to get support

If you need help, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket), or talk to the [Pinecone community](https://www.pinecone.io/community/). Ensure that your [plan tier](https://www.pinecone.io/pricing/) matches the support and availability SLAs you need. This may require you to upgrade to Enterprise.


# Security overview
Source: https://docs.pinecone.io/guides/production/security-overview

Overview of Pinecone security features for production: API keys, SSO, service accounts, audit logs, CMEK encryption, backups, and Private Endpoints.

## Access management

### API keys

Each Pinecone [project](/guides/projects/understanding-projects) has one or more [API keys](/guides/projects/manage-api-keys). In order to make calls to the Pinecone API, a user must provide a valid API key for the relevant Pinecone project.

You can [manage API key permissions](/guides/projects/manage-api-keys) in the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/keys). For the roles you can assign to an API key and the operations each role covers, see [Project roles](/guides/projects/understanding-projects#project-roles).

### Organization single sign-on (SSO)

SSO allows organizations to manage their teams' access to Pinecone through their identity management solution. Once your integration is configured, you can require that users from your domain sign in through SSO, and you can specify a default role for teammates when they sign up. SSO is available on Standard and Enterprise plans.

For more information, see [configure single sign on](/guides/production/configure-single-sign-on/okta).

### Role-based access controls (RBAC)

Pinecone uses role-based access controls (RBAC) to manage access to resources.

Service accounts, API keys, and users are all *principals*. A principal's access is determined by the *roles* assigned to it. Roles are assigned to a principal for a *resource*, either a project or an organization. The roles available to be assigned depend on the type of principal and resource.

You can manage roles in the [Pinecone console](https://app.pinecone.io) or programmatically with the Admin API. For more information, see [Manage roles and access](/guides/production/manage-rbac).

#### Service account roles

A service account can be assigned roles for the organization it belongs to, and any projects within that organization. For more information, see [Organization roles](/guides/organizations/understanding-organizations#organization-roles) and [Project roles](/guides/projects/understanding-projects#project-roles).

#### API key roles

An API key can be assigned any [project role](/guides/projects/understanding-projects#project-roles) except `ProjectOwner`, `ProjectManager`, and `ProjectMember`, and only for the project it belongs to. For more information, see [API keys](#api-keys).

#### User roles

A user can be assigned roles for each organization they belong to, and any projects within that organization. For more information, see [Organization roles](/guides/organizations/understanding-organizations#organization-roles) and [Project roles](/guides/projects/understanding-projects#project-roles).

## Compliance

<Note>
  To learn more about data privacy and compliance at Pinecone, visit the [Pinecone Trust and Security Center](https://security.pinecone.io/).
</Note>

### Audit logs

<Note>
  To enable and manage audit logs, you must be an [organization owner](/guides/organizations/understanding-organizations#organization-roles). This feature is available only on [Enterprise plans](https://www.pinecone.io/pricing/).
</Note>

[Audit logs](/guides/production/configure-audit-logs) provide a detailed record of user and API actions that occur within Pinecone.

Events are captured every 30 minutes and each log batch will be saved into its own file as a JSON blob, keyed by the time of the log to be written. Only logs since the integration was created and enabled will be saved.

Audit log events adhere to a standard JSON schema and include the following fields:

```jsonc JSON theme={null}
{
    "id": "00000000-0000-0000-0000-000000000000",
    "organization_id": "AA1bbbbCCdd2EEEe3FF",
    "organization_name": "example-org",
    "client": {
        "userAgent": "rawUserAgent"
    },
    "actor": {
        "principal_id": "00000000-0000-0000-0000-000000000000",
        "principal_name": "example@pinecone.io",
        "principal_type": "user", // user, api_key, service_account
        "display_name": "Example Person" // Only in case of user
    },
	"event": {
        "time": "2024-10-21T20:51:53.697Z",
        "action": "create",
        "resource_type": "index",
        "resource_id": "uuid",
        "resource_name": "docs-example",
        "outcome": {
            "result": "success",
            "reason": "", // Only displays for "result": "failure"
            "error_code": "", // Only displays for "result": "failure"
        },
        "parameters": { // Varies based on event
        }
	}
}
```

The following events are captured in the audit logs:

* [Organization events](#organization-events)
* [Project events](#project-events)
* [Index events](#index-events)
* [User and API key events](#user-and-api-key-events)
* [Security and governance events](#security-and-governance-events)

#### Organization events

| Action            | Query parameters                                                                                               |
| ----------------- | -------------------------------------------------------------------------------------------------------------- |
| Rename org        | `event.action: update`, `event.resource_type: organization`, `event.resource_id: NEW_ORG_NAME`                 |
| Delete org        | `event.action: delete`, `event.resource_type: organization`, `event.resource_id: DELETED_ORG_NAME`             |
| Create org member | `event.action: create`, `event.resource_type: user`, `event.resource_id: [ARRAY_OF_USER_EMAILS]`               |
| Update org member | `event.action: update`, `event.resource_type: user`, `event.resource_id: { user: USER_EMAIL, role: NEW_ROLE }` |
| Delete org member | `event.action: delete`, `event.resource_type: user`, `event.resource_id: USER_EMAIL`                           |

#### Project events

| Action                     | Query parameters                                                                                                   |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| Create project             | `event.action: create`, `event.resource_type: project`, `event.resouce_id: PROJ_NAME`                              |
| Update project             | `event.action: update`, `event.resource_type: project`, `event.resource_id: PROJECT_NAME`                          |
| Delete project             | `event.action: delete`, `event.resource_type: project`, `event.resource_id: PROJECT_NAME`                          |
| Invite project member      | `event.action: create`, `event.resource_type: user`, `event.resource_id: [ARRAY_OF_USER_EMAILS]`                   |
| Update project member role | `event.action: update`, `event.resource_type: user`, `event.resource_id: { user: USER_EMAIL, role: NEW_ROLE }`     |
| Delete project member      | `event.action: delete`, `event.resource_type: user`, `event.resource_id: { user: USER_EMAIL, project: PROJ_NAME }` |

#### Index events

| Action        | Query parameters                                                                        |
| ------------- | --------------------------------------------------------------------------------------- |
| Create index  | `event.action: create`, `event.resource_type: index`, `event.resouce_id: INDEX_NAME`    |
| Update index  | `event.action: update`, `event.resource_type: index`, `event.resource_id: INDEX_NAME`   |
| Delete index  | `event.action: delete`, `event.resource_type: index`, `event.resource_id: INDEX_NAME`   |
| Create backup | `event.action: create`, `event.resource_type: backup`, `event.resource_id: BACKUP_NAME` |
| Delete backup | `event.action: delete`, `event.resource_type: backup`, `event.resource_id: BACKUP_NAME` |

#### User and API key events

| Action         | Query parameters                                                                        |
| -------------- | --------------------------------------------------------------------------------------- |
| User login     | `event.action: login`, `event.resource_type: user`, `event.resouce_id: USERNAME`        |
| Create API key | `event.action: create`, `event.resource_type: api-key`, `event.resource_id: API_KEY_ID` |
| Delete API key | `event.action: delete`, `event.resource_type: api-key`, `event.resource_id: API_KEY_ID` |

#### Security and governance events

| Action                  | Query parameters                                                                                           |
| ----------------------- | ---------------------------------------------------------------------------------------------------------- |
| Create Private Endpoint | `event.action: create`, `event.resource_type: private-endpoints`, `event.resource_id: PRIVATE_ENDPOINT_ID` |
| Delete Private Endpoint | `event.action: delete`, `event.resource_type: private-endpoints`, `event.resource_id: PRIVATE_ENDPOINT_ID` |

## Data protection

### Customer-managed encryption keys (CMEK)

Data within a Pinecone project can be encrypted using [customer-managed encryption keys (CMEK)](/guides/production/configure-cmek). This allows you to encrypt your data using keys that you manage in your cloud provider's key management system (KMS). Pinecone supports CMEK using Amazon Web Services (AWS) KMS.

For [Bring your own cloud (BYOC)](/guides/production/bring-your-own-cloud), you use KMS on infrastructure in your own account rather than this console CMEK integration.

### Backup and recovery

<Note>
  This feature is available on [Standard and Enterprise plans](https://www.pinecone.io/pricing/).
</Note>

A backup is a static copy of your index that only consumes storage. It is a non-queryable representation of a set of records. You can [create a backup](/guides/manage-data/back-up-an-index) of an index, and you can [create a new index from a backup](/guides/manage-data/restore-an-index). This allows you to restore the index with the same or different configurations.

For more information, see [Understanding backups](/guides/manage-data/backups-overview).

### Encryption at rest

Pinecone encrypts stored data using the 256-bit Advanced Encryption Standard (AES-256) encryption algorithm.

### Encryption in transit

Pinecone uses standard protocols to encrypt user data in transit. Clients open HTTPS or gRPC connections to the Pinecone API; the Pinecone API gateway uses gRPC connections to user deployments in the cloud. These HTTPS and gRPC connections use the TLS 1.2 protocol with 256-bit Advanced Encryption Standard (AES-256) encryption.

<img alt="Diagram showing encryption protocols for user data in transit" />

Traffic is also encrypted in transit between the Pinecone backend and cloud infrastructure services, such as S3 and GCS. For more information, see [Google Cloud Platform](https://cloud.google.com/docs/security/encryption-in-transit) and [AWS security documentation](https://docs.aws.amazon.com/AmazonS3/userguide/UsingEncryption.html).

## Network security

<a />

### Private Endpoints

Use [Private Endpoints](/guides/production/configure-private-endpoints) to connect via AWS PrivateLink or Azure Private Link. This establishes private connectivity between your Pinecone serverless indexes and your cloud VPC/VNet while keeping traffic off the public internet.

<img alt="PrivateLink diagram" />

Private Endpoints are additive to other Pinecone security features: data is also [encrypted in transit](#encryption-in-transit), [encrypted at rest](#encryption-at-rest), and an [API key](#api-keys) is required to authenticate.

### Proxies

The following Pinecone SDKs support the use of proxies:

* [Python SDK](/reference/sdks/python/overview#proxy-configuration)
* [Node.js SDK](/reference/sdks/node/overview#proxy-configuration)


# Create a project
Source: https://docs.pinecone.io/guides/projects/create-a-project

Create a new Pinecone project in your organization using the console or Admin API, including project name, tags, and customer-managed encryption keys (CMEK).

This page shows you how to create a project.

If you are an [organization owner or organization manager](/guides/organizations/understanding-organizations#organization-roles), you can create a project in your organization:

<Tabs>
  <Tab title="Pinecone console">
    1. In the Pinecone console, go to [**your profile > Organization settings > Projects**](https://app.pinecone.io/organizations/-/settings/projects).

    2. Click **+ Create Project**.

    3. Enter a **Name**.

       <Note>
         A project name can contain up to 512 characters. For more information, see [Object identifiers](/reference/api/database-limits#identifier-limits).
       </Note>

    4. (Optional) Tags are key-value pairs that you can use to categorize and identify the project. To add a tag, click **+ Add tag** and enter a tag key and value.

    5. (Optional) Select **Encrypt with Customer Managed Encryption Key**. For more information, see [Configure CMEK](/guides/production/configure-cmek).

    6. Click **Create project**.

       To load an index with a [sample dataset](/guides/data/use-sample-datasets), click **Load sample data** and follow the prompts.

    <Note>
      The number of projects per organization varies by plan—see [Projects per organization](/reference/api/database-limits#projects-per-organization). To create additional projects, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan).
    </Note>
  </Tab>

  <Tab title="Code">
    <Note>
      An [access token](/guides/organizations/manage-service-accounts#retrieve-an-access-token) must be provided to complete this action through the Admin API.
    </Note>

    <CodeGroup>
      ```bash curl theme={null}
      PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

      curl "https://api.pinecone.io/admin/projects" \
          -H "X-Pinecone-Api-Version: 2025-10" \
      	-H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
      	-d '{
                "name":"example-project"
              }'
      ```

      ```bash CLI theme={null}
      # Target the organization for which you want to 
      # create a project.
      pc target -o "example-org"
      # Create the project and set it as the target 
      # project for the CLI.
      pc project create -n "example-project" --target
      ```
    </CodeGroup>

    The example returns a response like the following:

    <CodeGroup>
      ```json curl theme={null}
      {
        "id": "32c8235a-5220-4a80-a9f1-69c24109e6f2",
        "name": "example-project",
        "max_pods": 0,
        "force_encryption_with_cmek": false,
        "organization_id": "-NM7af6f234168c4e44a",
        "created_at": "2025-03-16T22:46:45.030Z"
      }
      ```

      ```text CLI theme={null}
      [SUCCESS] Project example-cli-project created successfully.

      ATTRIBUTE           VALUE
      Name                example-project
      ID                  32c8235a-5220-4a80-a9f1-69c24109e6f2
      Organization ID     -NM7af6f234168c4e44a
      Created At          2025-10-27 23:27:46.370088 +0000 UTC
      Force Encryption    false
      Max Pods            5

      [SUCCESS] Target project set to example-cli-project
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Next steps

* [Add users to your project](/guides/projects/manage-project-members#add-members-to-a-project)
* [Create an index](/guides/index-data/create-an-index)


# Manage API keys
Source: https://docs.pinecone.io/guides/projects/manage-api-keys

Create, view, update, and delete Pinecone API keys with custom permissions per project, including scoped roles and data plane access controls.

Each Pinecone [project](/guides/projects/understanding-projects) has one or more API keys. In order to [make calls to the Pinecone API](/guides/get-started/quickstart), you must provide a valid API key for the relevant Pinecone project.

This page shows you how to [create](#create-an-api-key), [view](#view-project-api-keys), [update](#update-an-api-key), and [delete](#delete-an-api-key) API keys.

<Warning>
  If you use custom API key permissions, ensure that you [target your index by host](/guides/manage-data/target-an-index#target-by-index-host-recommended) when performing data operations such as `upsert` and `query`.
</Warning>

## Create an API key

You can create a new API key for your project, as follows:

<Tabs>
  <Tab title="Pinecone console">
    1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects).

    2. Select your project.

    3. Go to **API keys**.

    4. Click **Create API key**.

    5. Enter an **API key name**.

    6. Select the **Permissions** to grant to the API key. For a description of the permission roles, see [Project roles](/guides/projects/understanding-projects#project-roles).

       <Note>
         Users on the Starter and Builder plans can set the permissions to **All** only. To customize the permissions further, [upgrade to the Standard or Enterprise plan](/guides/organizations/manage-billing/upgrade-billing-plan).
       </Note>

    7. Click **Create key**.

    8. Copy and save the generated API key in a secure place for future use.

       <Warning>
         You will not be able to see the API key again after you close the dialog.
       </Warning>

    9. Click **Close**.
  </Tab>

  <Tab title="Code">
    <Note>
      An [access token](/guides/organizations/manage-service-accounts#retrieve-an-access-token) must be provided to complete this action through the Admin API.
    </Note>

    <CodeGroup>
      ```bash curl theme={null}
      PINECONE_PROJECT_ID="YOUR_PROJECT_ID"
      PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

      curl -X POST "https://api.pinecone.io/admin/projects/$PINECONE_PROJECT_ID/api-keys" \
           -H "X-Pinecone-Api-Version: 2025-10" \
           -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
           -d '{
                 "name": "example-api-key",
                 "roles": ["ProjectEditor"]
               }'
      ```

      ```bash CLI theme={null}
      # Target the project for which you want to create an API key.
      pc target -o "example-org" -p "example-project"
      # Create the API key
      pc api-key create -n "example-api-key" --roles ProjectEditor
      ```
    </CodeGroup>

    The example returns a response like the following:

    <CodeGroup>
      ```json curl theme={null}
      {
        "key": {
          "id": "62b0dbfe-3489-4b79-b850-34d911527c88",
          "name": "example-api-key",
          "project_id": "32c8235a-5220-4a80-a9f1-69c24109e6f2",
          "roles": [
            "ProjectEditor"
          ],
          "created_at": "2025-10-20T23:40:27.069075Z"
        },
        "value": "..."
      }
      ```

      ```text CLI theme={null}
      ATTRIBUTE     VALUE
      Name          example-api-key
      ID            62b0dbfe-3489-4b79-b850-34d911527c88
      Value         ...
      Project ID    32c8235a-5220-4a80-a9f1-69c24109e6f2
      Roles         ProjectEditor
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## View project API keys

You can [view the API keys](/reference/api/latest/admin/list_api_keys) for your project:

<Tabs>
  <Tab title="Pinecone console">
    1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects).
    2. Select your project.
    3. Go to the **API keys** tab.

    You will see a list of all API keys for the project, including their names, IDs, and permissions.
  </Tab>

  <Tab title="Code">
    <Note>
      An [access token](/guides/organizations/manage-service-accounts#retrieve-an-access-token) must be provided to complete this action through the Admin API.
    </Note>

    <CodeGroup>
      ```bash curl theme={null}
      PINECONE_PROJECT_ID="32c8235a-5220-4a80-a9f1-69c24109e6f2"
      PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

      curl -X GET "https://api.pinecone.io/admin/projects/$PINECONE_PROJECT_ID/api-keys" \
           -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
           -H "X-Pinecone-Api-Version: 2025-10"
      ```

      ```bash CLI theme={null}
      PINECONE_PROJECT_ID="32c8235a-5220-4a80-a9f1-69c24109e6f2"

      pc api-key list -i $PINECONE_PROJECT_ID
      ```
    </CodeGroup>

    The example returns a response like the following:

    <CodeGroup>
      ```json curl theme={null}
      {
        "data": [
          {
            "id": "62b0dbfe-3489-4b79-b850-34d911527c88",
            "name": "example-api-key",
            "project_id": "32c8235a-5220-4a80-a9f1-69c24109e6f2",
            "roles": [
              "ProjectEditor"
            ],
            "created_at": "2025-10-20T23:39:43.665754Z"
          },
          {
            "id": "0d0d3678-81b4-4e0d-a4f0-70ba488acfb7",
            "name": "example-api-key-2",
            "project_id": "32c8235a-5220-4a80-a9f1-69c24109e6f2",
            "roles": [
              "ProjectEditor"
            ],
            "created_at": "2025-10-20T23:43:13.176422Z"
          }
        ]
      }
      ```

      ```text CLI theme={null}
      Organization: example-organization (ID: -NM7af6f234168c4e44a)
      Project: example-project (ID: 32c8235a-5220-4a80-a9f1-69c24109e6f2)

      API Keys

      NAME                 ID                                      PROJECT ID                              ROLES
      example-api-key      62b0dbfe-3489-4b79-b850-34d911527c88    32c8235a-5220-4a80-a9f1-69c24109e6f2    ProjectEditor
      example-api-key-2    0d0d3678-81b4-4e0d-a4f0-70ba488acfb7    32c8235a-5220-4a80-a9f1-69c24109e6f2    ProjectEditor
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## View API key details

You can [view the details of an API key](/reference/api/latest/admin/fetch_api_key):

<Tabs>
  <Tab title="Pinecone console">
    1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects).
    2. Select your project.
    3. Go to the **API keys** tab.
    4. In the row of the API key you want to change, in the **Actions** column, click **ellipsis (...) menu > Settings**.

    You will see the API key's name, ID, and permissions.
  </Tab>

  <Tab title="Code">
    <Note>
      An [access token](/guides/organizations/manage-service-accounts#retrieve-an-access-token) must be provided to complete this action through the Admin API.
    </Note>

    <CodeGroup>
      ```bash curl theme={null}
      PINECONE_API_KEY_ID="62b0dbfe-3489-4b79-b850-34d911527c88"
      PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

      curl -X GET "https://api.pinecone.io/admin/api-keys/$PINECONE_API_KEY_ID" \
           -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
           -H "accept: application/json" \
           -H "X-Pinecone-Api-Version: 2025-10"
      ```

      ```bash CLI theme={null}
      PINECONE_API_KEY_ID="62b0dbfe-3489-4b79-b850-34d911527c88"

      pc api-key describe -i $PINECONE_API_KEY_ID
      ```
    </CodeGroup>

    The example returns a response like the following:

    <CodeGroup>
      ```json curl theme={null}
      {
        "id": "62b0dbfe-3489-4b79-b850-34d911527c88",
        "name": "example-api-key",
        "project_id": "32c8235a-5220-4a80-a9f1-69c24109e6f2",
        "roles": [
          "ProjectEditor"
        ],
        "created_at": "2025-10-22T19:27:21.202955Z"
      }
      ```

      ```text CLI theme={null}
      ATTRIBUTE     VALUE
      Name          example-api-key
      ID            62b0dbfe-3489-4b79-b850-34d911527c88
      Project ID    32c8235a-5220-4a80-a9f1-69c24109e6f2
      Roles         ProjectEditor
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Update an API key

<Note>
  Users on the Starter and Builder plans cannot change API key permissions once they are set. Instead, [create a new API key](#create-an-api-key) or [upgrade to the Standard or Enterprise plan](/guides/organizations/manage-billing/upgrade-billing-plan).
</Note>

If you are a [project owner](/guides/projects/understanding-projects#project-roles), you can update the name and roles of an API key:

<Tabs>
  <Tab title="Pinecone console">
    1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects).

    2. Select your project.

    3. Go to the **API keys** tab.

    4. In the row of the API key you want to change, in the **Actions** column, click **ellipsis (...) menu > Settings**.

    5. Change the name and/or permissions for the API key as needed.

       For information about the different API key permissions, refer to [Project roles](/guides/projects/understanding-projects#project-roles).

    6. Click **Update**.
  </Tab>

  <Tab title="Code">
    <Note>
      An [access token](/guides/organizations/manage-service-accounts#retrieve-an-access-token) must be provided to complete this action through the Admin API.
    </Note>

    <CodeGroup>
      ```bash curl theme={null}
      PINECONE_API_KEY_ID="62b0dbfe-3489-4b79-b850-34d911527c88"
      PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

      curl -X PATCH "https://api.pinecone.io/admin/api-keys/$PINECONE_API_KEY_ID" \
           -H "X-Pinecone-Api-Version: 2025-10" \
           -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
           -d '{
                 "name": "new-api-key-name",
                 "roles": ["ProjectEditor"]
               }'
      ```

      ```bash CLI theme={null}
      PINECONE_API_KEY_ID="62b0dbfe-3489-4b79-b850-34d911527c88"

      # Target the organization that contains the API key.
      pc target -o "example-org"
      # Update the API key name.
      pc api-key update -i $PINECONE_API_KEY_ID -n "new-api-key-name"
      ```
    </CodeGroup>

    The example returns a response like the following:

    <CodeGroup>
      ```json curl theme={null}
      {
        "id": "62b0dbfe-3489-4b79-b850-34d911527c88",
        "name": "new-api-key-name",
        "project_id": "32c8235a-5220-4a80-a9f1-69c24109e6f2",
        "roles": [
          "ProjectEditor"
        ],
        "created_at": "2025-10-22T19:27:21.202955Z"
      }
      ```

      ```text CLI theme={null}
      ATTRIBUTE     VALUE
      Name          new-api-key-name
      ID            62b0dbfe-3489-4b79-b850-34d911527c88
      Project ID    32c8235a-5220-4a80-a9f1-69c24109e6f2
      Roles         ProjectEditor
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Delete an API key

If you are a [project owner](/guides/projects/understanding-projects#project-roles), you can delete your API key:

<Tabs>
  <Tab title="Pinecone console">
    1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects).
    2. Select your project.
    3. Go to the **API keys** tab.
    4. In the row of the API key you want to change, in the **Actions** column, click **ellipsis (...) menu > Delete**.
    5. Enter the **API key name**.
    6. Click **Confirm deletion**.

       <Warning>
         Deleting an API key is irreversible and will immediately disable any applications using the API key.
       </Warning>
  </Tab>

  <Tab title="Code">
    <Note>
      An [access token](/guides/organizations/manage-service-accounts#retrieve-an-access-token) must be provided to complete this action through the Admin API.
    </Note>

    <CodeGroup>
      ```bash curl theme={null}
      PINECONE_API_KEY_ID="62b0dbfe-3489-4b79-b850-34d911527c88"
      PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

      curl -X DELETE "https://api.pinecone.io/admin/api-keys/$PINECONE_API_KEY_ID" \
           -H "X-Pinecone-Api-Version: 2025-10" \
           -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN"
      ```

      ```bash CLI theme={null}
      PINECONE_API_KEY_ID="62b0dbfe-3489-4b79-b850-34d911527c88"

      # Delete the API key. Use --skip-confirmation to skip
      # the confirmation prompt.
      pc api-key delete -i $PINECONE_API_KEY_ID
      ```
    </CodeGroup>

    The example returns a response like the following:

    <CodeGroup>
      ```text curl theme={null}
      No response payload
      ```

      ```text CLI theme={null}
      [WARN] This operation will delete API key example-api-key from project example-project.
      [WARN] Any integrations that authenticate with this API key will immediately stop working.
      [WARN] This action cannot be undone.
      Do you want to continue? (y/N): y
      [INFO] You chose to continue delete.
      [SUCCESS] API key example-api-key deleted
      ```
    </CodeGroup>
  </Tab>
</Tabs>


# Manage project members
Source: https://docs.pinecone.io/guides/projects/manage-project-members

Add, remove, and update Pinecone project members using role-based access control (RBAC) to manage permissions and project owner roles.

[Organization owners](/guides/organizations/understanding-organizations#organization-roles) or [project owners](/guides/projects/understanding-projects#project-roles) can manage members in a project. Each member is assigned one or more [project roles](/guides/projects/understanding-projects#project-roles) that determine their permissions within the project.

To assign and manage roles programmatically with the Admin API, or to manage roles for service accounts and API keys, see [Manage roles and access](/guides/production/manage-rbac).

<Tip>
  For information about managing members at the **organization-level**, see [Manage organization members](/guides/organizations/manage-organization-members).
</Tip>

## Add members to a project

<Note>
  Project owners can add existing organization members to a project and manage their project roles. Only [organization owners](/guides/organizations/understanding-organizations#organization-roles) can invite people who are not yet members of the organization.
</Note>

You can add members to a project in the [Pinecone console](https://app.pinecone.io/organizations/-/projects):

1. Select your project.
2. Go to the [**Manage > Access > Members** tab](https://app.pinecone.io/organizations/-/projects/-/access/members).
3. Enter the member's email address or name.
4. Select a [**Project role**](/guides/projects/understanding-projects#project-roles) for the member. The role determines the member's permissions within Pinecone.
5. Click **Invite**.

When you invite a member to join your project, Pinecone sends them an email containing a link that enables them to gain access to the project. If they already have a Pinecone account, they still receive an email, but they can also immediately view the project.

## Change a member's role

You can change a member's role in the [Pinecone console](https://app.pinecone.io/organizations/-/projects):

1. Select your project.
2. Go to the [**Manage > Access > Members** tab](https://app.pinecone.io/organizations/-/projects/-/access/members).
3. In the row of the member you want to edit, click **ellipsis (...) menu > Edit role**.
4. Select a [**Project role**](/guides/projects/understanding-projects#project-roles) for the member.
5. Click **Edit role**.

## Remove a member

You can remove a member from a project in the [Pinecone console](https://app.pinecone.io/organizations/-/projects):

1. Select your project.
2. Go to the [**Manage > Access > Members** tab](https://app.pinecone.io/organizations/-/projects/-/access/members).
3. In the row of the member you want to remove, click **ellipsis (...) menu > Remove member**.
4. Click **Remove member**.

<Note>
  To remove yourself from a project, click the **Leave project** button in your user's row and confirm.
</Note>


# Manage projects
Source: https://docs.pinecone.io/guides/projects/manage-projects

View project details, rename projects, and delete projects in your Pinecone organization using the console or Admin API with owner permissions.

This page shows you how to view project details, rename a project, and delete a project.

<Note>
  You must be an [organization owner](/guides/organizations/understanding-organizations#organization-roles) or [project owner](/guides/projects/understanding-projects#project-roles) to edit project details or delete a project.
</Note>

## View project details

You can view the details of a project, as in the following example:

<Note>
  An [access token](/guides/organizations/manage-service-accounts#retrieve-an-access-token) must be provided to complete this action through the Admin API.
</Note>

<CodeGroup>
  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
  PROJECT_ID="32c8235a-5220-4a80-a9f1-69c24109e6f2"

  curl -X GET "https://api.pinecone.io/admin/projects/$PROJECT_ID" \
       -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
       -H "X-Pinecone-Api-Version: 2025-10" \
       -H "accept: application/json"
  ```

  ```bash CLI theme={null}
  PROJECT_ID="32c8235a-5220-4a80-a9f1-69c24109e6f2"

  # Target the organization that contains the project.
  pc target -o "example-org" 
  # Fetch the project details.
  pc project describe -i $PROJECT_ID
  ```
</CodeGroup>

The example returns a response like the following:

<CodeGroup>
  ```json curl theme={null}
  {
    "id": "32c8235a-5220-4a80-a9f1-69c24109e6f2",
    "name": "example-project",
    "max_pods": 5,
    "force_encryption_with_cmek": false,
    "organization_id": "-NM7af6f234168c4e44a",
    "created_at": "2025-10-27T23:27:46.370088Z"
  }
  ```

  ```text CLI theme={null}
  ATTRIBUTE           VALUE
  Name                example-project
  ID                  32c8235a-5220-4a80-a9f1-69c24109e6f2
  Organization ID     -NM7af6f234168c4e44a
  Created At          2025-10-27 23:27:46.370088 +0000 UTC
  Force Encryption    false
  Max Pods            5
  ```
</CodeGroup>

<Tip>
  You can view project details using the [Pinecone console](https://app.pinecone.io/organizations/-/settings/projects/-/indexes).
</Tip>

## Rename a project

You can change the name of your project:

<Tabs>
  <Tab title="Pinecone console">
    1. In the Pinecone console, go to [**Settings > Projects**](https://app.pinecone.io/organizations/-/settings/projects).

    2. Click the **ellipsis (...) menu > Configure** icon next to the project you want to update.

    3. Enter a new **Project Name**.

       <Note>
         A project name can contain up to 512 characters.
       </Note>

    4. Click **Save Changes**.
  </Tab>

  <Tab title="Code">
    <Note>
      An [access token](/guides/organizations/manage-service-accounts#retrieve-an-access-token) must be provided to complete this action through the Admin API.
    </Note>

    <CodeGroup>
      ```bash curl theme={null}
      PROJECT_ID="YOUR_PROJECT_ID"
      PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

      curl -X PATCH "https://api.pinecone.io/admin/projects/$PROJECT_ID" \
           -H "accept: application/json" \
           -H "Content-Type: application/json" \
           -H "X-Pinecone-Api-Version: 2025-10" \
           -d '{
                 "name": "updated-example-project"
               }'
      ```

      ```bash CLI theme={null}
      PROJECT_ID="YOUR_PROJECT_ID"

      # Target the project to update.
      pc target -o "example-org" "example-project"
      # Update the project name.
      pc project update -i $PROJECT_ID -n "updated-example-project"
      ```
    </CodeGroup>

    The example returns a response like the following:

    <CodeGroup>
      ```json curl theme={null}
      {
        "id": "32c8235a-5220-4a80-a9f1-69c24109e6f2",
        "name": "updated-example-project",
        "max_pods": 5,
        "force_encryption_with_cmek": false,
        "organization_id": "-NM7af6f234168c4e44a",
        "created_at": "2025-10-27T23:27:46.370088Z"
      }
      ```

      ```text CLI theme={null}
      [SUCCESS] Project 32c8235a-5220-4a80-a9f1-69c24109e6f2 updated successfully.
      ATTRIBUTE           VALUE
      Name                updated-example-project
      ID                  32c8235a-5220-4a80-a9f1-69c24109e6f2
      Organization ID     -NM7af6f234168c4e44a
      Created At          2025-10-27 23:27:46.370088 +0000 UTC
      Force Encryption    false
      Max Pods            5
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Add project tags

Project tags are key-value pairs that you can use to categorize and identify a project.

To add project tags, use the Pinecone console.

1. In the Pinecone console, go to [**Settings > Projects**](https://app.pinecone.io/organizations/-/settings/projects).
2. Click the **ellipsis (...) menu > Configure** icon next to the project you want to update.
3. Click **+ Add tag** and enter a tag key and value. Repeat for each tag you want to add.
4. Click **Save Changes**.

<Tip>
  You can also [add tags to indexes](/guides/manage-data/manage-indexes#configure-index-tags).
</Tip>

## Delete a project

To delete a project, you must first [delete all data](/guides/manage-data/delete-data), [indexes](/guides/manage-data/manage-indexes#delete-an-index), [collections](/guides/indexes/pods/back-up-a-pod-based-index#delete-a-collection), [backups](/guides/manage-data/back-up-an-index#delete-a-backup) and [assistants](/guides/assistant/manage-assistants#delete-an-assistant) associated with the project. Then, you can delete the project itself:

<Tabs>
  <Tab title="Pinecone console">
    1. In the Pinecone console, go to [**Settings > Projects**](https://app.pinecone.io/organizations/-/settings/projects).
    2. For the project you want to delete, click the **ellipsis (...) menu > Delete**.
    3. Enter the project name to confirm the deletion.
    4. Click **Delete Project**.
  </Tab>

  <Tab title="Code">
    <Note>
      An [access token](/guides/organizations/manage-service-accounts#retrieve-an-access-token) must be provided to complete this action through the Admin API.
    </Note>

    <CodeGroup>
      ```bash curl theme={null}
      PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
      PROJECT_ID="32c8235a-5220-4a80-a9f1-69c24109e6f2"

      curl -X DELETE "https://api.pinecone.io/admin/projects/$PROJECT_ID" \
           -H "X-Pinecone-Api-Version: 2025-10" \
           -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN"
      ```

      ```bash CLI theme={null}
      PINECONE_PROJECT_ID="32c8235a-5220-4a80-a9f1-69c24109e6f2"

      # Target the organization that contains the project.
      pc target -o "example-org" 
      # Delete the project. Use --skip-confirmation to skip 
      # the confirmation prompt.
      pc project delete -i $PINECONE_PROJECT_ID
      ```
    </CodeGroup>
  </Tab>
</Tabs>


# Manage service accounts at the project-level
Source: https://docs.pinecone.io/guides/projects/manage-service-accounts

Add service accounts to a Pinecone project and assign project roles to enable programmatic API access for automated workflows and CI pipelines.

<Note>
  This feature is in [public preview](/release-notes/feature-availability) and available only on [Enterprise plans](https://www.pinecone.io/pricing/).
</Note>

This page shows how [organization owners](/guides/organizations/understanding-organizations#organization-roles) and [project owners](/guides/projects/understanding-projects#project-roles) can add and manage service accounts at the project-level. Service accounts enable programmatic access to Pinecone's Admin API, which can be used to create and manage projects and API keys.

## Add a service account to a project

After a service account has been [added to an organization](/guides/organizations/manage-service-accounts#create-a-service-account), it can be added to a project in the [Pinecone console](https://app.pinecone.io/organizations/-/projects):

1. Select your project.
2. Go to the [**Manage > Access > Service accounts** tab](https://app.pinecone.io/organizations/-/projects/-/access/service-accounts).
3. Select the service account to add.
4. Select a [**Project role**](/guides/projects/understanding-projects#project-roles) for the service account. The role determines its permissions within Pinecone.
5. Click **Connect**.

## Change project role

To change a service account's role in the [Pinecone console](https://app.pinecone.io/organizations/-/projects):

1. Select your project.
2. Go to the [**Manage > Access > Service accounts** tab](https://app.pinecone.io/organizations/-/projects/-/access/service-accounts).
3. In the row of the service account you want to edit, click **ellipsis (...) menu > Edit role**.
4. Select a [**Project role**](/guides/projects/understanding-projects#project-roles) for the service account.
5. Click **Edit role**.

## Remove a service account from a project

To remove a service account from a project in the [Pinecone console](https://app.pinecone.io/organizations/-/projects):

1. Select your project.
2. Go to the [**Manage > Access > Service accounts** tab](https://app.pinecone.io/organizations/-/projects/-/access/service-accounts).
3. In the row of the service account you want to remove, click **ellipsis (...) menu > Disconnect**.
4. Enter the service account name to confirm.
5. Click **Disconnect**.


# Understanding projects
Source: https://docs.pinecone.io/guides/projects/understanding-projects

Learn how Pinecone projects organize indexes, cloud environments, API keys, and members, including project roles and per-role permission summaries.

A Pinecone project belongs to an [organization](/guides/organizations/understanding-organizations) and contains a number of [indexes](/guides/index-data/indexing-overview) and users. Only a user who belongs to the project can access the indexes in that project. Each project also has at least one project owner.

## Project environments

You choose a cloud environment for each index in a project. This makes it easy to manage related resources across environments and use the same API key to access them.

## Project roles

If you are an [organization owner](/guides/organizations/understanding-organizations#organization-roles) or project owner, you can manage who has access to a project. You grant a principal—a user, [service account](/guides/projects/manage-service-accounts), or [API key](/guides/projects/manage-api-keys)—access by assigning it one or more roles scoped to the project. A principal can hold more than one role, and its effective permissions are the union of all the roles it holds.

The roles you assign depend on the principal type:

* **Users and service accounts** are typically assigned a membership role—`ProjectOwner`, `ProjectManager`, or `ProjectMember`—optionally combined with one or more access roles.
* **API keys** are typically assigned `ProjectEditor` or `ProjectViewer`, or one or more access roles. API keys cannot be assigned `ProjectOwner`, `ProjectManager`, or `ProjectMember`, which include access to project settings, members, and API keys. To access these items programmatically, use a [service account](/guides/projects/manage-service-accounts).

The following project roles are available:

| Role                                        | Permissions                                                                                                                     |
| :------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------ |
| Project owner (`ProjectOwner`)              | Full access to the project, including members, API keys, and all resources and data.                                            |
| Project manager (`ProjectManager`)          | Read and write access to all resources and data. Read-only access to project settings, members, and API keys.                   |
| Project member (`ProjectMember`)            | Read-only access to project settings, members, and API keys. No resource or data access unless granted additional access roles. |
| Project editor (`ProjectEditor`)            | Read and write access to all resources and data. No access to project settings, members, or API keys.                           |
| Project viewer (`ProjectViewer`)            | Read-only access to all resources and data. No access to project settings, members, or API keys.                                |
| Control plane editor (`ControlPlaneEditor`) | Read and write access to control plane resources, such as indexes, assistants, backups, and collections.                        |
| Control plane viewer (`ControlPlaneViewer`) | Read-only access to control plane resources.                                                                                    |
| Data plane editor (`DataPlaneEditor`)       | Read and write access to data plane data, such as records, namespaces, and assistant files.                                     |
| Data plane viewer (`DataPlaneViewer`)       | Read-only access to data plane data.                                                                                            |

The following table details the project settings, resource, and data permissions for the owner, manager, and member roles:

| Permission                                                                  | Owner | Manager | Member |
| :-------------------------------------------------------------------------- | :---: | :-----: | :----: |
| View project settings, members, and API keys                                |   ✓   |    ✓    |    ✓   |
| Update project settings and configuration                                   |   ✓   |         |        |
| Delete the project                                                          |   ✓   |         |        |
| Manage project members and their roles                                      |   ✓   |         |        |
| Create and delete API keys                                                  |   ✓   |         |        |
| View indexes, assistants, backups, and collections                          |   ✓   |    ✓    |        |
| Create, configure, and delete indexes, assistants, backups, and collections |   ✓   |    ✓    |        |
| Read index data (query, fetch, list, and view stats)                        |   ✓   |    ✓    |        |
| Write index data (upsert, update, delete, and import)                       |   ✓   |    ✓    |        |

Specific to pod-based indexes:

<Warning>
  Customers who sign up for a Standard or Enterprise plan on or after August 18, 2025 cannot create pod-based indexes. Instead, create [serverless indexes](/guides/index-data/create-an-index), and consider using [dedicated read nodes](/guides/index-data/dedicated-read-nodes) for large workloads (millions of records or more, and moderate or high query rates).
</Warning>

| Permission                | Owner | Manager | Member |
| :------------------------ | :---: | :-----: | :----: |
| View project pod limits   |   ✓   |    ✓    |    ✓   |
| Update project pod limits |   ✓   |         |        |
| Update index size         |   ✓   |    ✓    |        |

<Note>
  Pod-based indexes do not support role-based access control and will always grant data plane read and write access to project members.
</Note>

### Role permissions

The following tables detail the operations covered by the general, control plane, and data plane roles:

#### General permissions

| Role            | Permissions                                     |
| :-------------- | :---------------------------------------------- |
| `ProjectEditor` | Permissions to read and write all project data. |
| `ProjectViewer` | Permissions to read all project data.           |

#### Control plane permissions

| Role                 | Permissions                                                                                                 |
| :------------------- | :---------------------------------------------------------------------------------------------------------- |
| `ControlPlaneEditor` | Permissions to list, describe, create, delete, and configure indexes, backups, collections, and assistants. |
| `ControlPlaneViewer` | Permissions to list and describe indexes, backups, collections, and assistants.                             |
| None                 | No control plane permissions.                                                                               |

#### Data plane permissions

| Role              | Permissions                                                                                                                                                                                                                                                                                                            |
| :---------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DataPlaneEditor` | <ul><li>Indexes: Permissions to query, import, fetch, add, update, and delete index data.</li><li>Pinecone Assistant: Permissions to add, list, view, and delete files; chat with an assistant, and evaluate responses.</li><li>Pinecone Inference: Permissions to generate embeddings and rerank documents.</li></ul> |
| `DataPlaneViewer` | <ul><li>Indexes: Permissions to query, fetch, list ID, and view stats.</li><li>Pinecone Assistant: Permissions to list and view files, chat with an assistant, and evaluate responses.</li><li>Pinecone Inference: Permissions to generate embeddings and rerank documents.</li></ul>                                  |
| None              | No data plane permissions.                                                                                                                                                                                                                                                                                             |

## API keys

Each Pinecone [project](/guides/projects/understanding-projects) has one or more API keys. In order to [make calls to the Pinecone API](/guides/get-started/quickstart), you must provide a valid API key for the relevant Pinecone project.

For more information, see [Manage API keys](/guides/projects/manage-api-keys).

## Project IDs

Each Pinecone project has a unique project ID.

To find the ID of a project, go to the project list in the [Pinecone console](https://app.pinecone.io/organizations/-/projects).

## See also

* [Understanding organizations](/guides/organizations/understanding-organizations)
* [Manage organization members](/guides/organizations/manage-organization-members)


# Filter by metadata
Source: https://docs.pinecone.io/guides/search/filter-by-metadata

Narrow Pinecone search results by adding metadata filter expressions to your query, using operators like $eq, $in, $gt, and $and for precise retrieval.

Every [record](/guides/get-started/concepts#record) in an index must contain an ID and a dense or sparse vector. In addition, you can include [metadata key-value pairs](/guides/index-data/indexing-overview#metadata) to store related information or context. When you search the index, you can then include a metadata filter to limit the search to records matching the filter expression.

## Search with a metadata filter

The following code searches for the 3 records that are most semantically similar to a query and that have a `category` metadata field with the value `digestive system`.

<Tabs>
  <Tab title="Search with text">
    <Note>
      Searching with text is supported only for [indexes with integrated embedding](/guides/index-data/indexing-overview#integrated-embedding).
    </Note>

    <CodeGroup>
      ```python Python theme={null}
      from pinecone import Pinecone

      pc = Pinecone(api_key="YOUR_API_KEY")

      # To get the unique host for an index, 
      # see https://docs.pinecone.io/guides/manage-data/target-an-index
      index = pc.Index(host="INDEX_HOST")

      filtered_results = index.search(
          namespace="example-namespace", 
          query={
              "inputs": {"text": "Disease prevention"}, 
              "top_k": 3,
              "filter": {"category": "digestive system"},
          },
          fields=["category", "chunk_text"]
      )

      print(filtered_results)
      ```

      ```javascript JavaScript theme={null}
      import { Pinecone } from '@pinecone-database/pinecone'

      const pc = new Pinecone({ apiKey: "YOUR_API_KEY" })

      // To get the unique host for an index, 
      // see https://docs.pinecone.io/guides/manage-data/target-an-index
      const namespace = pc.index("INDEX_NAME", "INDEX_HOST").namespace("example-namespace");

      const response = await namespace.searchRecords({
        query: {
          topK: 3,
          inputs: { text: "Disease prevention" },
          filter: { category: "digestive system" }
        },
        fields: ['chunk_text', 'category']
      });

      console.log(response);
      ```

      ```java Java theme={null}
      import io.pinecone.clients.Index;
      import io.pinecone.configs.PineconeConfig;
      import io.pinecone.configs.PineconeConnection;
      import org.openapitools.db_data.client.ApiException;
      import org.openapitools.db_data.client.model.SearchRecordsResponse;

      import java.util.*;

      public class SearchText {
          public static void main(String[] args) throws ApiException {
              PineconeConfig config = new PineconeConfig("YOUR_API_KEY");
              // To get the unique host for an index, 
              // see https://docs.pinecone.io/guides/manage-data/target-an-index
              config.setHost("INDEX_HOST");
              PineconeConnection connection = new PineconeConnection(config);

              Index index = new Index(config, connection, "integrated-dense-java");

              String query = "Disease prevention";
              List<String> fields = new ArrayList<>();
              fields.add("category");
              fields.add("chunk_text");

              Map<String, Object> filter = new HashMap<>();
              filter.put("category", "digestive system");

              // Search the index
              SearchRecordsResponse recordsResponse = index.searchRecordsByText(query,  "example-namespace", fields, 3, filter, null);

              // Print the results
              System.out.println(recordsResponse);
          }
      }
      ```

      ```go Go theme={null}
      package main

      import (
          "context"
          "encoding/json"
          "fmt"
          "log"

          "github.com/pinecone-io/go-pinecone/v4/pinecone"
      )

      func prettifyStruct(obj interface{}) string {
        	bytes, _ := json.MarshalIndent(obj, "", "  ")
          return string(bytes)
      }

      func main() {
          ctx := context.Background()

          pc, err := pinecone.NewClient(pinecone.NewClientParams{
              ApiKey: "YOUR_API_KEY",
          })
          if err != nil {
              log.Fatalf("Failed to create Client: %v", err)
          }

          // To get the unique host for an index, 
          // see https://docs.pinecone.io/guides/manage-data/target-an-index
          idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST", Namespace: "example-namespace"})
          if err != nil {
              log.Fatalf("Failed to create IndexConnection for Host: %v", err)
          } 

          metadataMap := map[string]interface{}{
              "category": map[string]interface{}{
                  "$eq": "digestive system",
              },
          }
          res, err := idxConnection.SearchRecords(ctx, &pinecone.SearchRecordsRequest{
              Query: pinecone.SearchRecordsQuery{
                  TopK: 3,
                  Inputs: &map[string]interface{}{
                      "text": "Disease prevention",
                  },
                  Filter: &metadataMap,
              },
              Fields: &[]string{"chunk_text", "category"},
          })
          if err != nil {
              log.Fatalf("Failed to search records: %v", err)
          }
          fmt.Printf(prettifyStruct(res))
      }
      ```

      ```shell curl theme={null}
      INDEX_HOST="INDEX_HOST"
      NAMESPACE="YOUR_NAMESPACE"
      PINECONE_API_KEY="YOUR_API_KEY"

      curl "https://$INDEX_HOST/records/namespaces/$NAMESPACE/search" \
        -H "Accept: application/json" \
        -H "Content-Type: application/json" \
        -H "Api-Key: $PINECONE_API_KEY" \
        -H "X-Pinecone-Api-Version: unstable" \
        -d '{
              "query": {
                  "inputs": {"text": "Disease prevention"},
                  "top_k": 3,
                  "filter": {"category": "digestive system"}
              },
              "fields": ["category", "chunk_text"]
           }'
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Search with a vector">
    <CodeGroup>
      ```Python Python theme={null}
      from pinecone.grpc import PineconeGRPC as Pinecone

      pc = Pinecone(api_key="YOUR_API_KEY")

      # To get the unique host for an index, 
      # see https://docs.pinecone.io/guides/manage-data/target-an-index
      index = pc.Index(host="INDEX_HOST")

      index.query(
          namespace="example-namespace",
          vector=[0.0236663818359375,-0.032989501953125, ..., -0.01041412353515625,0.0086669921875], 
          top_k=3,
          filter={
              "category": {"$eq": "digestive system"}
          },
          include_metadata=True,
          include_values=False
      )
      ```

      ```JavaScript JavaScript theme={null}
      import { Pinecone } from '@pinecone-database/pinecone'

      const pc = new Pinecone({ apiKey: "YOUR_API_KEY" })

      // To get the unique host for an index, 
      // see https://docs.pinecone.io/guides/manage-data/target-an-index
      const index = pc.index("INDEX_NAME", "INDEX_HOST")

      const queryResponse = await index.namespace('example-namespace').query({
          vector: [0.0236663818359375,-0.032989501953125,...,-0.01041412353515625,0.0086669921875],
          topK: 3,
          filter: {
              "category": { "$eq": "digestive system" }
          }
          includeValues: false,
          includeMetadata: true,
      });
      ```

      ```java Java theme={null}
      import com.google.protobuf.Struct;
      import com.google.protobuf.Value;
      import io.pinecone.clients.Index;
      import io.pinecone.configs.PineconeConfig;
      import io.pinecone.configs.PineconeConnection;
      import io.pinecone.unsigned_indices_model.QueryResponseWithUnsignedIndices;

      import java.util.Arrays;
      import java.util.List;

      public class QueryExample {
          public static void main(String[] args) {
              PineconeConfig config = new PineconeConfig("YOUR_API_KEY");
              // To get the unique host for an index, 
              // see https://docs.pinecone.io/guides/manage-data/target-an-index
              config.setHost("INDEX_HOST");
              PineconeConnection connection = new PineconeConnection(config);
              Index index = new Index(connection, "INDEX_NAME");
              List<Float> query = Arrays.asList(0.0236663818359375f, -0.032989501953125f, ..., -0.01041412353515625f, 0.0086669921875f);
              Struct filter = Struct.newBuilder()
                      .putFields("category", Value.newBuilder()
                              .setStructValue(Struct.newBuilder()
                                      .putFields("$eq", Value.newBuilder()
                                              .setStringValue("digestive system")
                                              .build()))
                              .build())
                      .build();

              QueryResponseWithUnsignedIndices queryResponse = index.query(1, query, null, null, null, "example-namespace", filter, false, true);
              System.out.println(queryResponse);
          }
      }
      ```

      ```go Go theme={null}
      package main

      import (
          "context"
          "encoding/json"
          "fmt"
          "log"

          "github.com/pinecone-io/go-pinecone/v4/pinecone"
      )

      func prettifyStruct(obj interface{}) string {
      	bytes, _ := json.MarshalIndent(obj, "", "  ")
      	return string(bytes)
      }

      func main() {
          ctx := context.Background()

          pc, err := pinecone.NewClient(pinecone.NewClientParams{
              ApiKey: "YOUR_API_KEY",
          })
          if err != nil {
              log.Fatalf("Failed to create Client: %v", err)
          }

          // To get the unique host for an index, 
          // see https://docs.pinecone.io/guides/manage-data/target-an-index
          idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST", Namespace: "example-namespace"})
          if err != nil {
              log.Fatalf("Failed to create IndexConnection for Host: %v", err)
        	}

          queryVector := []float32{0.0236663818359375,-0.032989501953125,...,-0.01041412353515625,0.0086669921875}

          metadataMap := map[string]interface{}{
              "category": map[string]interface{}{
                  "$eq": "digestive system",
              }
          }

          metadataFilter, err := structpb.NewStruct(metadataMap)
          if err != nil {
              log.Fatalf("Failed to create metadata map: %v", err)
          }

          res, err := idxConnection.QueryByVectorValues(ctx, &pinecone.QueryByVectorValuesRequest{
              Vector:          queryVector,
              TopK:            3,
              MetadataFilter: metadataFilter,
              IncludeValues:   false,
              includeMetadata: true,
          })
          if err != nil {
              log.Fatalf("Error encountered when querying by vector: %v", err)
          } else {
              fmt.Printf(prettifyStruct(res))
          }
      }
      ```

      ```bash curl theme={null}
      # To get the unique host for an index,
      # see https://docs.pinecone.io/guides/manage-data/target-an-index
      PINECONE_API_KEY="YOUR_API_KEY"
      INDEX_HOST="INDEX_HOST"

      curl "https://$INDEX_HOST/query" \
        -H "Api-Key: $PINECONE_API_KEY" \
        -H 'Content-Type: application/json' \
        -H "X-Pinecone-Api-Version: 2025-10" \
        -d '{
              "vector": [0.0236663818359375,-0.032989501953125,...,-0.01041412353515625,0.0086669921875],
              "namespace": "example-namespace",
              "topK": 3,
              "filter": {"category": {"$eq": "digestive system"}},
              "includeMetadata": true,
              "includeValues": false
          }'
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Metadata filter expressions

Pinecone's filtering language supports the following operators:

| Operator  | Function                                                                                                                   | Supported types         |
| :-------- | :------------------------------------------------------------------------------------------------------------------------- | :---------------------- |
| `$eq`     | Matches  with metadata values that are equal to a specified value. Example: `{"genre": {"$eq": "documentary"}}`            | Number, string, boolean |
| `$ne`     | Matches  with metadata values that are not equal to a specified value. Example: `{"genre": {"$ne": "drama"}}`              | Number, string, boolean |
| `$gt`     | Matches  with metadata values that are greater than a specified value. Example: `{"year": {"$gt": 2019}}`                  | Number                  |
| `$gte`    | Matches  with metadata values that are greater than or equal to a specified value. Example:`{"year": {"$gte": 2020}}`      | Number                  |
| `$lt`     | Matches  with metadata values that are less than a specified value. Example: `{"year": {"$lt": 2020}}`                     | Number                  |
| `$lte`    | Matches  with metadata values that are less than or equal to a specified value. Example: `{"year": {"$lte": 2020}}`        | Number                  |
| `$in`     | Matches  with metadata values that are in a specified array. Example: `{"genre": {"$in": ["comedy", "documentary"]}}`      | String, number          |
| `$nin`    | Matches  with metadata values that are not in a specified array. Example: `{"genre": {"$nin": ["comedy", "documentary"]}}` | String, number          |
| `$exists` | Matches  with the specified metadata field. Example: `{"genre": {"$exists": true}}`                                        | Number, string, boolean |
| `$and`    | Joins query clauses with a logical `AND`. Example: `{"$and": [{"genre": {"$eq": "drama"}}, {"year": {"$gte": 2020}}]}`     | -                       |
| `$or`     | Joins query clauses with a logical `OR`. Example: `{"$or": [{"genre": {"$eq": "drama"}}, {"year": {"$gte": 2020}}]}`       | -                       |

<Note>
  Only `$and` and `$or` are allowed at the top level of the query expression.
</Note>

<Note>
  Each `$in` or `$nin` operator accepts a maximum of 10,000 values. Exceeding this limit will cause the request to fail. For more information, see [Metadata filter limits](/reference/api/database-limits#metadata-filter-limits).
</Note>

For example, the following has a `"genre"` metadata field with a list of strings:

```JSON JSON theme={null}
{ "genre": ["comedy", "documentary"] }
```

This means `"genre"` takes on both values, and requests with the following filters will match:

```JSON JSON theme={null}
{"genre":"comedy"}

{"genre": {"$in":["documentary","action"]}}

{"$and": [{"genre": "comedy"}, {"genre":"documentary"}]}
```

However, requests with the following filter will **not** match:

```JSON JSON theme={null}
{ "$and": [{ "genre": "comedy" }, { "genre": "drama" }] }
```

Additionally, requests with the following filters will **not** match because they are invalid. They will result in a compilation error:

```json JSON theme={null}
# INVALID QUERY:
{"genre": ["comedy", "documentary"]}
```

```json JSON theme={null}
# INVALID QUERY:
{"genre": {"$eq": ["comedy", "documentary"]}}
```


# Full-text search
Source: https://docs.pinecone.io/guides/search/full-text-search

Upsert and search typed JSON documents in Pinecone with BM25 scoring, Lucene query syntax, dense and sparse vector ranking, and metadata filters.

<Note>
  Full-text search is in [public preview](#public-preview). APIs may continue to evolve before general availability.
</Note>

<Tip>
  You can also use the Pinecone console to create indexes with document schemas, upsert documents, search documents, and fetch or delete documents by ID.
</Tip>

Full-text search ranks documents by keyword and phrase relevance using **BM25** scoring, with optional **Lucene** query syntax. Because an index with a document schema can also declare dense and sparse vector fields, the same index can rank by semantic or sparse-vector similarity, so one index can cover keyword and semantic search.

**When to use it.** Reach for full-text search when exact words, phrases, names, codes, or identifiers matter, not just semantic similarity. For semantic-only or vector-only workloads, an [index with dense vectors](/guides/get-started/concepts#index-with-dense-vectors) (the vector API) is simpler; see [Search overview](/guides/search/search-overview) to choose the right approach.

### Capabilities

What full-text search does and doesn't match:

| Capability                      | Status                                                                                                                                                                                                                     |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Fuzzy matching (typo tolerance) | Supported in `query_string` queries only ([query syntax](#query-syntax-reference))                                                                                                                                         |
| Stemming                        | Supported, opt-in per field at index creation ([stemming](#stemming))                                                                                                                                                      |
| Stop-word removal               | Supported, opt-in per field at index creation ([tokens & analyzers](#tokens-and-analyzers))                                                                                                                                |
| Substring / n-gram matching     | Supported, opt-in per field at index creation. Can't be combined with stemming or stop words on the same field ([n-grams](#substring-search-with-n-grams))                                                                 |
| Synonym expansion               | Not supported. A search for `car` won't match a document containing only `automobile`. Use [semantic search](/guides/search/semantic-search) or [hybrid search](/guides/search/hybrid-search) for synonyms or paraphrases. |

**The path, end to end.** Create an index with a [schema](#schema-definition) that declares your ranking fields, upsert your data as JSON documents, then search by choosing one ranking signal per search request with `score_by`. The [end-to-end example](#end-to-end-example) below stitches all three steps into one runnable script, and the sections after it cover each operation in detail.

Pinecone's document API stores typed fields you declare in a schema. How it works:

1. You upsert data as JSON **documents**.
2. You declare how each field should be indexed via a **schema** — as a `string` field with `full_text_search` enabled (BM25 scoring), a `dense_vector` field, or a `sparse_vector` field. The schema is for ranking fields only; metadata fields are not declared.
3. Pinecone indexes each field's content according to the type of the field declared in the schema. Any other fields on the upserted documents are automatically stored and indexed for filtering — no schema declaration required.

Supported schema field types:

* **Text fields** (`type: "string"` with a `full_text_search` config object — for example, `{ "language": "en" }`; `{}` is also valid and uses the same defaults) — indexed for BM25 ranking and Lucene queries.
* **Dense vector fields** (`type: "dense_vector"`) — indexed for ANN similarity search.
* **Sparse vector fields** (`type: "sparse_vector"`) — indexed for sparse vector similarity search.

Filterable metadata is not part of the schema. Any field you upsert that is not declared in the schema is stored on the document, returned via `include_fields`, and automatically indexed for filtering — see [Metadata fields](#metadata-fields).

**Every search picks exactly one ranking signal.** The `score_by` clause selects the scoring method for the request:

* `text` — BM25 token matching on a single FTS-enabled `string` field.
* `query_string` — Lucene query syntax across one or more FTS-enabled `string` fields, including cross-field boolean queries.
* `dense_vector` — vector similarity against a `dense_vector` field.
* `sparse_vector` — sparse-vector similarity against a `sparse_vector` field.

The same index can support all four when the schema declares the corresponding fields, but a given request commits to one. To narrow the candidates a vector ranking sees, combine the `score_by` with a metadata filter — including the text-match operators `$match_phrase`, `$match_all`, and `$match_any` on FTS-enabled `string` fields, plus the standard logical and comparison operators (`$and`, `$or`, `$not`, `$exists`, etc.). The filter narrows what's eligible; the `score_by` ranks what remains. This is the most common hybrid pattern.

For example, on an index whose schema declares both a `dense_vector` field (`review_embedding`) and an FTS-enabled `string` field (`review_text`), this single request runs semantic search across the corpus but only over documents whose `review_text` contains the exact phrase "beautifully written":

```python Python theme={null}
index.documents.search(
    namespace="reviews",
    top_k=5,
    score_by=[
        {
            "type": "dense_vector",
            "field": "review_embedding",
            "values": query_embedding,
        }
    ],
    filter={"review_text": {"$match_phrase": "beautifully written"}},
)
```

The dense ranking still controls the order of results; the text-match filter just narrows what's eligible to be ranked.

### End-to-end example

A complete run from index creation through search. Copy this into a single file, set `PINECONE_API_KEY`, and run.

```python Python theme={null}
import os
import time
from pinecone import Pinecone
from pinecone.preview import SchemaBuilder

pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"])

# 1. Create an index. Setting `full_text_search` on a `string` field enables BM25.
schema = (
    SchemaBuilder()
      .add_string_field(name="title", full_text_search={"language": "en"})
      .add_string_field(name="body", full_text_search={"language": "en"})
      .build()
)
pc.preview.indexes.create(name="articles-quickstart", schema=schema)

# Wait for the index to be ready before upserting (no timeout — add a loop cap in production).
while not pc.preview.indexes.describe(name="articles-quickstart").status.ready:
    time.sleep(2)

index = pc.preview.index(name="articles-quickstart")

# 2. Upsert documents. Fields declared in the schema (`title`, `body`) are
#    BM25-indexed; any extra fields (`category`, `year`) are stored on the
#    document and auto-indexed for filtering as metadata.
index.documents.upsert(
    namespace="example-namespace",
    documents=[
        {
            "_id": "doc1",
            "title": "Machine learning in 2024",
            "body": "Machine learning models are revolutionizing natural language processing",
            "category": "technology",
            "year": 2024,
        },
        {
            "_id": "doc2",
            "title": "Vector databases",
            "body": "Vector databases enable fast similarity search across embeddings",
            "category": "technology",
            "year": 2023,
        },
        {
            "_id": "doc3",
            "title": "Quantum computing",
            "body": "Quantum computers leverage superposition for faster computation",
            "category": "science",
            "year": 2024,
        },
    ],
)

# 3. Search with BM25 ranking on `body`, narrowed by a metadata filter and a
#    phrase-match text filter on the FTS field. The relevance score comes back
#    as `_score` (not `score`).
response = index.documents.search(
    namespace="example-namespace",
    top_k=5,
    score_by=[
        {
            "type": "text",
            "field": "body",
            "query": "machine learning",
        }
    ],
    filter={
        "year": {"$gte": 2024},
        "body": {"$match_phrase": "natural language"},
    },
    include_fields=["title", "body", "category", "year"],
)

for match in response.matches:
    print(match._id, match._score, getattr(match, "title", ""))
```

What each piece does:

* **`SchemaBuilder().add_string_field(..., full_text_search={"language": "en"})`** declares a BM25-indexed text field. Without `full_text_search`, the `string` field would be rejected at index creation — schemas only declare ranking fields.
* **`index.documents.upsert(...)`** writes plain JSON documents. Schema fields are validated; non-schema fields (`category`, `year` here) are stored and auto-indexed for filtering.
* **`score_by=[{"type": "text", ...}]`** picks BM25 as the ranking method. One ranking method per request; combine ranking with text matching via `filter` rather than mixing score methods.
* **`filter`** narrows candidates *before* ranking. Standard operators (`$eq`, `$gte`, etc.) apply to any metadata field; the text-match operators (`$match_phrase`, `$match_all`, `$match_any`) only apply to FTS-enabled `string` fields.
* **`_score`** is the system-owned relevance score. A user metadata field named `score` would be returned alongside, untouched.

The Python SDK reference further down covers every operation individually; the example above stitches the most common path into one runnable script.

### Filters vs. scoring

Filters are deterministic — each document either matches or it doesn't — and they apply before scoring. Scoring methods (`text`/BM25, `query_string`/Lucene, `dense_vector`, `sparse_vector`) order whatever remains after filtering, and only the top `top_k` hits are returned (max 10,000).

When you're combining text matching with vector ranking, start with the hard yes/no constraints as filters (including the text-match operators `$match_phrase`, `$match_all`, `$match_any` on FTS-enabled `string` fields), then pick a `score_by` method to rank whatever remains. Use BM25 (`score_by` `text` or `query_string`) when keyword and phrase ranking *order* matters, not just inclusion.

<Note>
  An index with a document schema can store both `dense_vector` and `sparse_vector` fields, plus one or more `string` fields with `full_text_search` enabled. A single search request scores results with one ranking method at a time: dense vector, sparse vector, BM25 text, or Lucene query syntax. You can still combine vector ranking with full-text keyword matching in one request by using a text-match filter, such as `$match_phrase`, `$match_all`, or `$match_any`. The vector search ranks the matching documents; the full-text filter narrows the set of documents to search.
</Note>

## Schema definition

The schema is required at index creation and declares the fields that drive ranking or vector search. Filterable metadata is not declared in the schema — any field you upsert that is not declared in the schema is automatically stored and indexed for filtering.

**Schema field types:**

| Type            | Purpose                                                                                                              | Key options                                                                            |
| --------------- | -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `dense_vector`  | ANN similarity search                                                                                                | `dimension` (required), `metric` (`cosine`, `dotproduct`, `euclidean`)                 |
| `sparse_vector` | Sparse-vector similarity search with values from a custom sparse encoder                                             | —                                                                                      |
| `string` (text) | Full-text search. Set `full_text_search` to enable BM25 — for example, `{ "language": "en" }`, or `{}` for defaults. | `language`, `stemming`, `stop_words`, `ngram` (all optional, under `full_text_search`) |

<Note>
  Schemas can only declare ranking fields. Declaring a metadata-only field (a `string` field without `full_text_search`, or a `string_list`, `float`, or `boolean` field) is rejected at index creation with a 400 error. Metadata fields are auto-indexed at upsert time. See [Metadata fields](#metadata-fields).
</Note>

**Reserved names.** Field names must be unique, non-empty strings, and **must not start with `_` or `$`**. The `_` prefix is reserved for system-managed fields (for example, `_id`, `_score`); `$` is reserved for filter operators. Field names are also limited to **64 bytes**. Every document has a required `_id` field, which carries its unique identifier. A user metadata field named `score` is allowed — match scores are returned as `_score` to avoid collisions.

<Note>
  In public preview, indexes with document schemas do not support integrated inference fields such as `semantic_text`. To use dense or sparse vector ranking in an index with a document schema, declare a `dense_vector` or `sparse_vector` field and provide vector values at upsert time.
</Note>

<Note>
  A `string` field with `full_text_search` is not metadata and does not count toward the 40 KB metadata limit for records. Use these FTS-enabled `string` fields for searchable chunk text. In public preview, indexes with document schemas do not support combining integrated inference fields, such as `semantic_text` fields, with full-text-search fields. To combine semantic ranking with full-text search, declare a `dense_vector` field alongside one or more FTS-enabled `string` fields and provide dense vector values when you upsert documents.
</Note>

**Example: text-only schema** (minimal `{}` enables FTS with all defaults; sub-fields like `language`, `stemming`, and `stop_words` are optional overrides)

```json theme={null}
{
  "name": "articles",
  "deployment": {
    "deployment_type": "managed",
    "cloud": "aws",
    "region": "us-east-1"
  },
  "schema": {
    "fields": {
      "title": {
        "type": "string",
        "full_text_search": { "language": "en" }
      },
      "body": {
        "type": "string",
        "description": "The main body text of the article",
        "full_text_search": {
          "language": "en",
          "stemming": true,
          "stop_words": true
        }
      }
    }
  }
}
```

<Note>
  Including `full_text_search`, even an empty object `{}`, is what turns full-text search on for a `string` field. Without it, the field is rejected at index creation, because schemas only declare ranking fields.
</Note>

**Example: text + dense + sparse vector (multi-field) schema**

```json theme={null}
{
  "name": "articles-hybrid",
  "deployment": {
    "deployment_type": "managed",
    "cloud": "aws",
    "region": "us-east-1"
  },
  "schema": {
    "fields": {
      "title": {
        "type": "string",
        "full_text_search": { "language": "en" }
      },
      "body": {
        "type": "string",
        "full_text_search": { "language": "en" }
      },
      "embedding": {
        "type": "dense_vector",
        "dimension": 1536,
        "metric": "cosine"
      },
      "sparse_embedding": {
        "type": "sparse_vector"
      }
    }
  }
}
```

Documents upserted into either schema can carry additional fields — for example, `category` (string), `tags` (array of strings), `year` (number), or `in_stock` (boolean). These fields are stored on the document, returned via `include_fields`, and automatically indexed for filtering. They do not need to be declared in the schema.

### Metadata fields

Metadata fields are **not declared in the schema**. Any field you include on an upserted document that is not declared in the schema is treated as metadata: it is stored on the document, returned via `include_fields`, and automatically indexed for filtering with the standard operators (`$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`, `$exists`, `$and`, `$or`, `$not`).

Metadata field types are inferred from the values you upsert: strings, numbers (stored as floating point), booleans, and arrays of strings are all supported. You can mix metadata field types across documents in the same index.

<Warning>
  Schema migration is not yet supported. Once an index is created, you cannot add, remove, or modify fields. Plan your schema carefully.
</Warning>

## API and SDK reference

Full-text search uses API version `2026-01.alpha`. All requests require the header `X-Pinecone-Api-Version: 2026-01.alpha`.

The endpoints below are split into control-plane operations (project-scoped, authenticated against `api.pinecone.io`) and data-plane operations (index-scoped, authenticated against the per-index `INDEX_HOST.svc.<region>.pinecone.io` host returned by `DescribeIndex`). The preview SDK reflects the same split: `pc.preview.*` for control-plane FTS operations and `pc.preview.index(...).documents.*` for data-plane document operations.

### Control plane operations

Control plane operations manage indexes and their configuration.

<AccordionGroup>
  <Accordion title="Create index (POST /indexes)">
    Creates a new index with the provided schema. The index initializes asynchronously; poll the describe endpoint to know when it's ready for data operations.

    **Example request — on-demand read capacity (default)**

    ```bash theme={null}
    curl -X POST "https://api.pinecone.io/indexes" \
      -H "Api-Key: {{YOUR_API_KEY}}" \
      -H "Content-Type: application/json" \
      -H "X-Pinecone-Api-Version: 2026-01.alpha" \
      -d '{
        "name": "articles",
        "deployment": {
          "deployment_type": "managed",
          "cloud": "aws",
          "region": "us-east-1"
        },
        "schema": {
          "fields": {
            "title": {
              "type": "string",
              "full_text_search": { "language": "en" }
            },
            "body": {
              "type": "string",
              "full_text_search": { "language": "en" }
            }
          }
        },
        "read_capacity": { "mode": "OnDemand" },
        "deletion_protection": "disabled"
      }'
    ```

    **Example request — dedicated read capacity**

    ```bash theme={null}
    curl -X POST "https://api.pinecone.io/indexes" \
      -H "Api-Key: {{YOUR_API_KEY}}" \
      -H "Content-Type: application/json" \
      -H "X-Pinecone-Api-Version: 2026-01.alpha" \
      -d '{
        "name": "articles-dedicated",
        "deployment": {
          "deployment_type": "managed",
          "cloud": "aws",
          "region": "us-east-1"
        },
        "schema": {
          "fields": {
            "content": {
              "type": "string",
              "full_text_search": { "language": "en" }
            }
          }
        },
        "read_capacity": {
          "mode": "Dedicated",
          "dedicated": {
            "node_type": "b1",
            "scaling": "Manual",
            "manual": { "shards": 1, "replicas": 1 }
          }
        },
        "deletion_protection": "disabled"
      }'
    ```

    Request parameters:

    * `name` (string, optional) - Unique index name (lowercase alphanumeric and hyphens, 1-45 characters). Auto-generated if omitted.
    * `deployment` (object, optional) - Deployment configuration. Defaults to `managed` on AWS `us-east-1` if omitted.
      * `deployment_type` (string) - `"managed"` for serverless, `"pod"` for pod-based, `"byoc"` for bring-your-own-cloud.
      * For `managed`: `cloud` (`"aws"` | `"gcp"` | `"azure"`), `region` (e.g., `"us-east-1"`).
    * `schema` (object, required) - Schema definition. See [Schema definition](#schema-definition) for all supported field types. Each field in `schema.fields` uses the `type` discriminator to select its configuration:

      * `dense_vector`: `dimension` (required), `metric` (required, one of `cosine`, `dotproduct`, `euclidean`).
      * `sparse_vector`: no additional options.
      * `string` (text): `full_text_search: { ... }` (object); optional sub-fields `language`, `stemming`, `stop_words`, and `ngram` (`{ min_gram, max_gram, prefix_only }`, for [substring search](#substring-search-with-n-grams)).
      * Any field may also include an optional `description` (string) — free-text documentation of what the field contains. It's stored on the schema and returned by describe-index, and is especially useful for agentic workflows where an LLM inspects the schema to decide how to query the index.

      Metadata-only fields (`string` without `full_text_search`, `string_list`, `float`, `boolean`) are not allowed in the schema and are rejected at index creation. Metadata fields are auto-indexed for filtering at upsert time — see [Metadata fields](#metadata-fields).
    * `read_capacity` (object, optional) - Read capacity for serverless (managed) indexes:
      * `mode: "OnDemand"` — default; auto-scaled shared read capacity.
      * `mode: "Dedicated"` — provisioned read nodes. Requires a `dedicated` block with `node_type`, `scaling`, and (for `Manual` scaling) `manual: { shards, replicas }`.
    * `deletion_protection` (string, optional) - `"enabled"` or `"disabled"` (default: `"disabled"`).
    * `tags` (object, optional) - Key-value tags for the index.

    **Schema constraints:**

    * Field names must be unique within the schema.
    * Field names must contain only alphanumeric characters and underscores, must not start with `_` (reserved for system-managed fields like `_id` and `_score`) or `$` (reserved for filter operators), and must be at most 64 bytes.
    * The schema must contain at least one field.

    **Example response**

    **Status:** 201 Created

    ```json theme={null}
    {
      "id": "e51ea4e1-2dda-4607-94dc-9054b1fa8492",
      "name": "articles",
      "host": "articles-jweaq8m.svc.aped-4627-b74a.pinecone.io",
      "status": {
        "ready": false,
        "state": "Initializing"
      },
      "deployment": {
        "deployment_type": "managed",
        "cloud": "aws",
        "region": "us-east-1",
        "environment": "aped-4627-b74a"
      },
      "schema": {
        "version": "v1",
        "fields": {
          "title": {
            "type": "string",
            "description": null,
            "full_text_search": {
              "language": "en",
              "stemming": false,
              "stop_words": false,
              "lowercase": true,
              "max_token_length": 40
            }
          },
          "body": {
            "type": "string",
            "description": null,
            "full_text_search": {
              "language": "en",
              "stemming": false,
              "stop_words": false,
              "lowercase": true,
              "max_token_length": 40
            }
          }
        }
      },
      "read_capacity": {
        "mode": "OnDemand",
        "status": { "state": "Ready" }
      },
      "tags": null,
      "deletion_protection": "disabled"
    }
    ```

    The response shows fields with **server-applied defaults**. Each FTS-enabled field's `full_text_search` block returns the full resolved analyzer config: the settable subset (`language`, `stemming`, `stop_words`) reflects what was passed at index creation (or its default when omitted), and `lowercase` and `max_token_length` are server-applied defaults that aren't settable from the request. All fields include `description` (`null` if not supplied at creation).

    Wait for `status.ready: true` before performing data plane operations. For `Dedicated` read capacity, also wait for `read_capacity.status.state: "Ready"`.

    Response fields:

    * `id` (string) — Unique index ID.
    * `name` (string) — Index name.
    * `host` (string) — Per-index host URL for data-plane operations (`INDEX_HOST.svc.<region>.pinecone.io`).
    * `status` (object) — Provisioning status.
      * `ready` (boolean) — Whether the index is ready for data-plane operations.
      * `state` (string) — Current state, e.g., `"Initializing"`, `"Ready"`.
    * `deployment` (object) — Resolved deployment configuration.
      * `deployment_type` (string) — e.g., `"managed"`.
      * `cloud` (string) — Cloud provider.
      * `region` (string) — Region code.
      * `environment` (string) — Environment identifier assigned by the system.
    * `schema` (object) — Resolved schema with server-applied defaults.
      * `version` (string) — Schema version, e.g., `"v1"`.
      * `fields` (object) — Map of field name → resolved field definition. See note above on `full_text_search` server-applied defaults.
    * `read_capacity` (object) — Resolved read capacity configuration.
      * `mode` (string) — `"OnDemand"` or `"Dedicated"`.
      * `dedicated` (object, present when `mode: "Dedicated"`) — Dedicated read-node configuration: `node_type`, `scaling`, and (for `Manual` scaling) `manual.{ shards, replicas }`.
      * `status` (object) — Read-capacity provisioning status.
        * `state` (string) — e.g., `"Migrating"`, `"Ready"`.
        * `current_shards` (integer or null, `Dedicated` only) — Current number of provisioned shards.
        * `current_replicas` (integer or null, `Dedicated` only) — Current number of provisioned replicas.
    * `tags` (object or null) — Key-value tags, or `null` if none.
    * `deletion_protection` (string) — `"enabled"` or `"disabled"`.
  </Accordion>

  <Accordion title="List indexes (GET /indexes)">
    Returns all indexes in the project, including their current status and configuration.

    ```bash theme={null}
    curl -X GET "https://api.pinecone.io/indexes" \
      -H "Api-Key: {{YOUR_API_KEY}}" \
      -H "X-Pinecone-Api-Version: 2026-01.alpha"
    ```

    **Status:** 200 OK. Returns an array of index objects, each with the same structure as the create-index response.
  </Accordion>

  <Accordion title="Describe index (GET /indexes/{index_name})">
    Returns detailed information about a specific index, including its schema, status, and host URL.

    ```bash theme={null}
    curl -X GET "https://api.pinecone.io/indexes/articles" \
      -H "Api-Key: {{YOUR_API_KEY}}" \
      -H "X-Pinecone-Api-Version: 2026-01.alpha"
    ```

    **Status:** 200 OK. Returns the same structure as the create-index response.
  </Accordion>

  <Accordion title="Update index (PATCH /indexes/{index_name})">
    Updates index configuration. Currently, only `deletion_protection` can be updated.

    ```bash theme={null}
    curl -X PATCH "https://api.pinecone.io/indexes/articles" \
      -H "Api-Key: {{YOUR_API_KEY}}" \
      -H "Content-Type: application/json" \
      -H "X-Pinecone-Api-Version: 2026-01.alpha" \
      -d '{ "deletion_protection": "enabled" }'
    ```

    **Status:** 200 OK. Returns the updated index configuration.
  </Accordion>

  <Accordion title="Delete index (DELETE /indexes/{index_name})">
    Permanently deletes an index and all its data. If `deletion_protection` is enabled, you must first disable it using the update endpoint.

    ```bash theme={null}
    curl -X DELETE "https://api.pinecone.io/indexes/articles" \
      -H "Api-Key: {{YOUR_API_KEY}}" \
      -H "X-Pinecone-Api-Version: 2026-01.alpha"
    ```

    **Status:** 202 Accepted (empty body).
  </Accordion>
</AccordionGroup>

### Data plane operations

<Note>
  Data plane operations include a namespace in the URL path. Namespaces partition documents within an index: they're auto-created on first upsert and completely isolated from each other. Use `"__default__"` if you don't need partitioning. If your documents are in another namespace, search, fetch, and delete requests must target that namespace.
</Note>

<AccordionGroup>
  <Accordion title="Upsert documents (POST /namespaces/{namespace}/documents/upsert)">
    Inserts or updates documents. If a document with the same `_id` exists, it is completely replaced. Documents are indexed asynchronously and may not be searchable immediately after upsert.

    **Example request**

    ```bash theme={null}
    curl -X POST "https://articles-abc123.svc.us-east-1.pinecone.io/namespaces/__default__/documents/upsert" \
      -H "Api-Key: {{YOUR_API_KEY}}" \
      -H "Content-Type: application/json" \
      -H "X-Pinecone-Api-Version: 2026-01.alpha" \
      -d '{
        "documents": [
          {
            "_id": "doc1",
            "title": "Machine learning in 2024",
            "body": "Machine learning models are revolutionizing natural language processing",
            "category": "technology",
            "year": 2024
          },
          {
            "_id": "doc2",
            "title": "Vector databases",
            "body": "Vector databases enable fast similarity search across embeddings",
            "category": "technology",
            "year": 2023
          },
          {
            "_id": "doc3",
            "title": "Quantum computing",
            "body": "Quantum computers leverage superposition for faster computation",
            "category": "science",
            "year": 2024
          }
        ]
      }'
    ```

    Path parameters:

    * `namespace` (string, required) - Namespace name (use `"__default__"` if not using namespaces).

    Body parameters:

    * `documents` (array, required, 1-1000 items) - Array of documents to upsert. Each document is an object with:
      * `_id` (string, required) - Unique document ID. If a document with this `_id` already exists, it is replaced entirely. If multiple documents in the same batch share an `_id`, only the last one is stored.
      * Fields matching your schema. Additional fields are stored on the document and auto-indexed for filtering as metadata. Names starting with `_` or `$` are rejected.

    Limits:

    * Each upsert request can contain up to 1000 documents and must be no larger than 2 MB.
    * Each document can be no larger than 2 MB.
    * Each `full_text_search` string field can be no larger than 100 KB and can contain up to 10,000 tokens.
    * Each token can be no larger than 256 bytes before analyzer truncation.
    * Metadata fields on a document (everything outside FTS-enabled `string` fields) are limited to 40 KB per document in total. This metadata limit does not apply to `full_text_search` text fields.

    **Example response**

    **Status:** 202 Accepted

    ```json theme={null}
    {
      "upserted_count": 3
    }
    ```

    Response fields:

    * `upserted_count` (integer) - Number of documents accepted for upsert.

    #### Schema validation

    Each item in the `documents` array is validated against your index schema. If any item fails validation, **the entire request fails** and nothing is upserted.

    | Scenario                                                             | Result                                                            |
    | -------------------------------------------------------------------- | ----------------------------------------------------------------- |
    | Field value doesn't match declared type (for schema-declared fields) | **Error** — request fails                                         |
    | Document or request exceeds a size or count limit                    | **Error** — request fails                                         |
    | Field not in schema                                                  | Stored on the document and auto-indexed for filtering as metadata |
    | Field name starts with `_` or `$`                                    | **Error** — request fails                                         |
    | Schema field missing from item                                       | OK — schema fields are optional unless stated otherwise           |
    | Document missing `_id`                                               | **Error** — request fails                                         |
  </Accordion>

  <Accordion title="Search documents (POST /namespaces/{namespace}/documents/search)">
    Searches documents using any one of four scoring methods: BM25 token matching (`text`), Lucene query syntax (`query_string`), dense vector similarity (`dense_vector`), or sparse vector similarity (`sparse_vector`). Optionally filter by field values before scoring.

    <Tip>
      To populate an initial view before a user enters a query, use `query_string` with `query: "*"`. This returns `top_k` documents in an arbitrary order; it is not relevance-ranked keyword search.
    </Tip>

    **Example request**

    ```bash theme={null}
    curl -X POST "https://articles-abc123.svc.us-east-1.pinecone.io/namespaces/__default__/documents/search" \
      -H "Api-Key: {{YOUR_API_KEY}}" \
      -H "Content-Type: application/json" \
      -H "X-Pinecone-Api-Version: 2026-01.alpha" \
      -d '{
        "include_fields": ["title", "body", "category", "year"],
        "score_by": [{
          "type": "text",
          "field": "body",
          "query": "machine learning"
        }],
        "top_k": 10
      }'
    ```

    Path parameters:

    * `namespace` (string, required) - Namespace name (use `"__default__"` if not using namespaces).

    Body parameters:

    * `include_fields` (array, optional) - List of field names to return in results. Defaults to `[]` if omitted (or `null`); each match then returns only `_id` and `_score` with no stored fields. Use `["*"]` to return all stored fields (including fields not declared in the schema). User metadata fields named `score` are returned alongside the system-owned `_score` match score.
    * `score_by` (array, required) - Array of scoring methods. A single search request ranks by one scoring type. Multi-field BM25 is supported: pass several `text` clauses (one per field) or use a single `query_string` clause whose query targets multiple fields, and every contributing field weighs equally; there is no per-clause weight parameter. To combine BM25 ranking with `dense_vector` or `sparse_vector` ranking, restrict the dense (or sparse) search with a text-match filter on the lexical field (`$match_phrase`, `$match_all`, `$match_any`) or run separate searches and merge results client-side. Each item must be one of:
      * **`type: "text"`** — BM25 token matching on a single text field. Multi-word queries use OR-style matching (case-insensitive). Phrase constraints are not supported here; use `query_string` with quoted terms for exact-phrase ranking.
        * `field` (string, required) — Name of a text-searchable field.
        * `query` (string, required) — One or more words to search for.
      * **`type: "query_string"`** — Lucene query syntax. Supports boolean operators, phrase prefix matching, boosting, fuzzy matching (`term~`, `term~N`), and cross-field queries.

        * `query` (string, required) — A Lucene query string (see [query syntax reference](#query-syntax-reference)). Target a specific field with Lucene field qualifiers directly in the query string: `notes:friendship`, or combine fields with boolean operators: `title:(alpha) OR body:(beta)`. The query runs against all text-searchable fields in the index when no field qualifier is specified.

        <Warning>
          `query_string` does not accept a `field` or `fields` parameter. Passing either returns a `400` error. Use Lucene field qualifiers in the query string itself to target specific fields: `fieldname:value` or `fieldname:(multi word value)`.
        </Warning>
      * **`type: "dense_vector"`** — Dense vector similarity ranking. Requires a `dense_vector` field in the schema.
        * `field` (string, required) — Name of the dense-vector field to score against.
        * `values` (array of floats, required) — Query vector.
      * **`type: "sparse_vector"`** — Sparse vector similarity ranking. Requires a `sparse_vector` field in the schema.
        * `field` (string, required) — Name of the sparse-vector field to score against.
        * `sparse_values` (object, required) — `{ "indices": [...], "values": [...] }`.
    * `top_k` (integer, required) - Number of results to return (1-10000).
    * `filter` (object, optional) - Filter conditions applied before scoring. Filter on any metadata field on your documents (auto-indexed at upsert time) or use the text match operators (`$match_phrase`, `$match_all`, `$match_any`) on FTS-enabled `string` fields. Supports the filter operators below.

    **Search limits:**

    | Limit                        | Value  | Description                                                                    |
    | ---------------------------- | ------ | ------------------------------------------------------------------------------ |
    | Max `score_by` clauses       | 100    | Maximum number of clauses in the `score_by` array                              |
    | Max total `score_by` payload | 100 KB | Maximum encoded size of all `score_by` clauses combined                        |
    | Max per-clause query size    | 10 KB  | Maximum size of the `query` string in a single `text` or `query_string` clause |

    #### Filter operators

    Filters are applied *before* the search runs. The search only considers documents that match the filter.

    | Operator        | Example                                                                 | Description                                                                                          |
    | --------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
    | `$eq`           | `{"category": {"$eq": "tech"}}`                                         | Equals                                                                                               |
    | `$ne`           | `{"category": {"$ne": "tech"}}`                                         | Not equals                                                                                           |
    | `$gt`           | `{"year": {"$gt": 2023}}`                                               | Greater than                                                                                         |
    | `$gte`          | `{"year": {"$gte": 2023}}`                                              | Greater than or equal                                                                                |
    | `$lt`           | `{"year": {"$lt": 2025}}`                                               | Less than                                                                                            |
    | `$lte`          | `{"year": {"$lte": 2025}}`                                              | Less than or equal                                                                                   |
    | `$in`           | `{"category": {"$in": ["a", "b"]}}`                                     | In list                                                                                              |
    | `$nin`          | `{"category": {"$nin": ["a", "b"]}}`                                    | Not in list                                                                                          |
    | `$exists`       | `{"category": {"$exists": true}}`                                       | Field has a value (`true`) or is absent (`false`).                                                   |
    | `$match_phrase` | `{"body": {"$match_phrase": "machine learning"}}`                       | Exact phrase match (contiguous tokens) on a text-searchable field. Compose with any `score_by` type. |
    | `$match_all`    | `{"body": {"$match_all": "machine learning"}}`                          | All tokens present, in any order, on a text-searchable field.                                        |
    | `$match_any`    | `{"body": {"$match_any": "AI robotics"}}`                               | At least one token present, on a text-searchable field.                                              |
    | `$and`          | `{"$and": [{"category": {"$eq": "tech"}}, {"year": {"$gte": 2024}}]}`   | Logical AND of the listed clauses.                                                                   |
    | `$or`           | `{"$or": [{"category": {"$eq": "tech"}}, {"category": {"$eq": "ai"}}]}` | Logical OR of the listed clauses.                                                                    |
    | `$not`          | `{"$not": {"category": {"$eq": "archive"}}}`                            | Negation of the wrapped clause.                                                                      |

    By default, multiple fields at the top level of a `filter` object are combined with implicit AND semantics. Use `$and`, `$or`, and `$not` to build explicit compound conditions (they can nest).

    The text match operators (`$match_phrase`, `$match_all`, `$match_any`) share a few rules:

    * **Where they apply.** Fields declared with a `full_text_search` config object.
    * **Tokenization.** They reuse the field's configured tokenizer and stemmer — a token that matches in BM25 scoring will match in a text match filter.
    * **Value limit.** Each operator accepts at most **128 tokens** in its value.
    * **Lucene-style operators.** Phrase slop (`"phrase"~N`), term boosting (`^N`), and phrase prefix (`"phrase pre"*`) are not parsed — values are literal text and match semantics come from the operator name. To use those operators, score with `query_string`.
    * **Composition.** They compose freely with metadata operators under `$and`, `$or`, and `$not` at any nesting level:

    ```json theme={null}
    {
      "$and": [
        { "body": { "$match_all": "federal reserve" } },
        { "category": { "$eq": "finance" } },
        { "year": { "$gte": 2024 } }
      ]
    }
    ```

    <Warning>
      Filters, including text match operators (`$match_phrase`, `$match_all`, `$match_any`), are only valid on `POST /namespaces/{namespace}/documents/search`. The `POST /namespaces/{namespace}/documents/fetch` endpoint is **ID-only**, and `POST /namespaces/{namespace}/documents/delete` accepts only `ids` or `delete_all`. To act on documents matching a metadata expression, search to retrieve matching IDs (capped at `top_k`, max 10,000 per request), then fetch or delete by ID. To remove all documents in a namespace in one call, use `delete_all` instead.
    </Warning>

    #### More examples

    **Token matching with filter:**

    ```bash theme={null}
    curl -X POST "https://articles-abc123.svc.us-east-1.pinecone.io/namespaces/__default__/documents/search" \
      -H "Api-Key: {{YOUR_API_KEY}}" \
      -H "Content-Type: application/json" \
      -H "X-Pinecone-Api-Version: 2026-01.alpha" \
      -d '{
        "include_fields": ["title", "body", "category", "year"],
        "filter": {
          "category": { "$eq": "technology" },
          "year": { "$gte": 2024 }
        },
        "score_by": [{
          "type": "text",
          "field": "body",
          "query": "machine learning"
        }],
        "top_k": 10
      }'
    ```

    **Cross-field boolean query with `query_string`:**

    ```bash theme={null}
    curl -X POST "https://articles-abc123.svc.us-east-1.pinecone.io/namespaces/__default__/documents/search" \
      -H "Api-Key: {{YOUR_API_KEY}}" \
      -H "Content-Type: application/json" \
      -H "X-Pinecone-Api-Version: 2026-01.alpha" \
      -d '{
        "include_fields": ["title", "body"],
        "score_by": [{
          "type": "query_string",
          "query": "title:(quantum) OR body:(machine learning)"
        }],
        "top_k": 10
      }'
    ```

    **Dense vector ranking with a phrase-match filter:**

    ```bash theme={null}
    curl -X POST "https://articles-abc123.svc.us-east-1.pinecone.io/namespaces/__default__/documents/search" \
      -H "Api-Key: {{YOUR_API_KEY}}" \
      -H "Content-Type: application/json" \
      -H "X-Pinecone-Api-Version: 2026-01.alpha" \
      -d '{
        "include_fields": ["title", "body"],
        "filter": { "body": { "$match_phrase": "machine learning" } },
        "score_by": [{
          "type": "dense_vector",
          "field": "embedding",
          "values": [0.12, 0.34, 0.56]
        }],
        "top_k": 10
      }'
    ```

    **Sparse vector ranking:**

    ```bash theme={null}
    curl -X POST "https://articles-abc123.svc.us-east-1.pinecone.io/namespaces/__default__/documents/search" \
      -H "Api-Key: {{YOUR_API_KEY}}" \
      -H "Content-Type: application/json" \
      -H "X-Pinecone-Api-Version: 2026-01.alpha" \
      -d '{
        "include_fields": ["title", "body"],
        "score_by": [{
          "type": "sparse_vector",
          "field": "sparse_embedding",
          "sparse_values": {
            "indices": [12, 287, 4096],
            "values": [0.41, 0.33, 0.18]
          }
        }],
        "top_k": 10
      }'
    ```

    **Text match filter with BM25 ranking:**

    ```bash theme={null}
    curl -X POST "https://articles-abc123.svc.us-east-1.pinecone.io/namespaces/__default__/documents/search" \
      -H "Api-Key: {{YOUR_API_KEY}}" \
      -H "Content-Type: application/json" \
      -H "X-Pinecone-Api-Version: 2026-01.alpha" \
      -d '{
        "include_fields": ["body", "category", "year"],
        "filter": {
          "$and": [
            { "body": { "$match_all": "federal reserve" } },
            { "category": { "$eq": "finance" } }
          ]
        },
        "score_by": [{
          "type": "text",
          "field": "body",
          "query": "monetary policy impact"
        }],
        "top_k": 10
      }'
    ```

    This restricts the candidate set to finance articles whose `body` contains both "federal" and "reserve", then ranks those candidates by BM25 score against "monetary policy impact".

    **Phrase filter with negation:**

    ```bash theme={null}
    curl -X POST "https://articles-abc123.svc.us-east-1.pinecone.io/namespaces/__default__/documents/search" \
      -H "Api-Key: {{YOUR_API_KEY}}" \
      -H "Content-Type: application/json" \
      -H "X-Pinecone-Api-Version: 2026-01.alpha" \
      -d '{
        "include_fields": ["body", "category"],
        "filter": {
          "$and": [
            { "body": { "$match_phrase": "large language model" } },
            { "body": { "$not": { "$match_any": "spam advertisement" } } }
          ]
        },
        "score_by": [{
          "type": "text",
          "field": "body",
          "query": "recent advances in generative AI"
        }],
        "top_k": 10
      }'
    ```

    This requires the exact phrase "large language model" and excludes documents containing "spam" or "advertisement".

    **Example response**

    **Status:** 200 OK

    ```json theme={null}
    {
      "matches": [
        {
          "_id": "doc1",
          "_score": 0.8234,
          "title": "Machine learning in 2024",
          "body": "Machine learning models are revolutionizing natural language processing",
          "category": "technology",
          "year": 2024
        }
      ],
      "namespace": "__default__",
      "usage": { "read_units": 1 }
    }
    ```

    Response fields:

    * `matches` (array) - Ranked matches, most relevant first.
      * `_id` (string) - Document ID.
      * `_score` (float) - Relevance score (higher is better). The leading underscore prevents collision with user-defined metadata fields named `score`.
      * Plus any fields requested via `include_fields`.
    * `namespace` (string) - Namespace searched.
    * `usage` (object) - `read_units` consumed.
  </Accordion>

  <Accordion title="Fetch documents (POST /namespaces/{namespace}/documents/fetch)">
    Fetches documents by ID. Fetch is **ID-only** — the endpoint does not accept a `filter` parameter. To retrieve documents matching a metadata expression, use `POST /namespaces/{namespace}/documents/search` with a `filter` instead.

    **Example request — fetch by ids**

    ```bash theme={null}
    curl -X POST "https://articles-abc123.svc.us-east-1.pinecone.io/namespaces/__default__/documents/fetch" \
      -H "Api-Key: {{YOUR_API_KEY}}" \
      -H "Content-Type: application/json" \
      -H "X-Pinecone-Api-Version: 2026-01.alpha" \
      -d '{
        "ids": ["doc1", "doc2"],
        "include_fields": ["title", "body", "category"]
      }'
    ```

    Body parameters:

    * `ids` (array of strings, required, 1-1000 items) - Document IDs to fetch. Must contain at least one ID; an empty array returns a 400 error.
    * `include_fields` (array of strings, optional) - Field names to include. If omitted, all fields are returned.

    **Example response**

    **Status:** 200 OK

    ```json theme={null}
    {
      "documents": {
        "doc1": {
          "_id": "doc1",
          "title": "Machine learning in 2024",
          "body": "Machine learning models are revolutionizing natural language processing",
          "category": "technology"
        },
        "doc2": {
          "_id": "doc2",
          "title": "Vector databases",
          "body": "Vector databases enable fast similarity search across embeddings",
          "category": "technology"
        }
      },
      "namespace": "__default__",
      "usage": { "read_units": 2 }
    }
    ```

    Response fields:

    * `documents` (object) - Map of document ID to the returned fields (including `_id`).
    * `namespace` (string) - Namespace fetched from.
    * `usage` (object) - `read_units` consumed.
  </Accordion>

  <Accordion title="Delete documents (POST /namespaces/{namespace}/documents/delete)">
    Deletes documents from a namespace. You must specify exactly one of `ids` or `delete_all`. Delete does not accept a `filter` parameter — to delete documents matching a metadata expression, fetch their IDs via `POST /namespaces/{namespace}/documents/search` first, then pass them to delete.

    **Example request — delete by ids**

    ```bash theme={null}
    curl -X POST "https://articles-abc123.svc.us-east-1.pinecone.io/namespaces/__default__/documents/delete" \
      -H "Api-Key: {{YOUR_API_KEY}}" \
      -H "Content-Type: application/json" \
      -H "X-Pinecone-Api-Version: 2026-01.alpha" \
      -d '{ "ids": ["doc1", "doc2"] }'
    ```

    **Example request — delete all in namespace**

    ```bash theme={null}
    curl -X POST "https://articles-abc123.svc.us-east-1.pinecone.io/namespaces/__default__/documents/delete" \
      -H "Api-Key: {{YOUR_API_KEY}}" \
      -H "Content-Type: application/json" \
      -H "X-Pinecone-Api-Version: 2026-01.alpha" \
      -d '{ "delete_all": true }'
    ```

    Body parameters (specify exactly one):

    * `ids` (array of strings, 1-1000 items) - Document IDs to delete.
    * `delete_all` (boolean) - If `true`, delete all documents in the namespace.

    **Example response**

    **Status:** 202 Accepted

    ```json theme={null}
    {}
    ```
  </Accordion>
</AccordionGroup>

## Python SDK

<Tip>
  For a runnable end-to-end example, see this [Google Colab notebook](https://colab.research.google.com/drive/1lsPeNLCJ2ucbYthHYs9WpybW4nAfB8tG), which demonstrates upserting and searching a sample Wikipedia dataset.
</Tip>

### Installation

Full-text search is available in the standard `pinecone` Python SDK under the `pc.preview.*` namespace, which gates the alpha API surface. Make sure you have a recent version of the SDK installed.

```sh theme={null}
pip install --upgrade pinecone
```

<Note>
  FTS endpoints are accessed via `pc.preview.*` for control-plane operations and `pc.preview.index(...).documents.*` for data-plane document operations. The `preview` namespace makes the alpha status explicit and isolates FTS APIs from the GA `pc.indexes.*` and `pc.index(...)` namespaces used by the vector API.
</Note>

### Control plane

<AccordionGroup>
  <Accordion title="Instantiate the client">
    ```python theme={null}
    import os
    from pinecone import Pinecone

    pc = Pinecone(
      api_key=os.environ.get('PINECONE_API_KEY')
    )
    ```
  </Accordion>

  <Accordion title="Create index (on-demand read capacity)">
    ```python theme={null}
    from pinecone.preview import SchemaBuilder

    schema = (
        SchemaBuilder()
          .add_string_field(name="title", full_text_search={"language": "en"})
          .add_string_field(name="body", full_text_search={"language": "en", "stemming": True})
          .build()
    )

    index_model = pc.preview.indexes.create(
        name="articles",
        schema=schema,
        read_capacity={"mode": "OnDemand"},
    )

    host = index_model.host
    ```
  </Accordion>

  <Accordion title="Create index (dedicated read capacity)">
    ```python theme={null}
    from pinecone.preview import SchemaBuilder

    schema = (
        SchemaBuilder()
          .add_string_field(name="content", full_text_search={"language": "en"})
          .build()
    )

    index_model = pc.preview.indexes.create(
        name="articles-dedicated",
        schema=schema,
        read_capacity={
            "mode": "Dedicated",
            "dedicated": {
                "node_type": "b1",
                "scaling": "Manual",
                "manual": {"shards": 1, "replicas": 1},
            },
        },
    )
    ```
  </Accordion>

  <Accordion title="Describe index">
    ```python theme={null}
    index_model = pc.preview.indexes.describe(name="articles")
    print(index_model.status, index_model.schema)
    ```
  </Accordion>

  <Accordion title="List indexes">
    ```python theme={null}
    for idx in pc.preview.indexes.list():
        print(idx.name, idx.status)
    ```
  </Accordion>

  <Accordion title="Check whether an index exists">
    ```python theme={null}
    if pc.preview.indexes.exists(name="articles"):
        index_model = pc.preview.indexes.describe(name="articles")
    ```
  </Accordion>

  <Accordion title="Update index configuration">
    ```python theme={null}
    pc.preview.indexes.configure(
        name="articles",
        deletion_protection="enabled",
        tags={"env": "prod"},
    )
    ```

    Use `configure` to update mutable settings on an existing index (for example, deletion protection or index tags). Schema changes are not supported in public preview.
  </Accordion>

  <Accordion title="Delete index">
    ```python theme={null}
    pc.preview.indexes.delete(name="articles")
    ```
  </Accordion>
</AccordionGroup>

### Data plane

<AccordionGroup>
  <Accordion title="Build a data plane client">
    ```python theme={null}
    index = pc.preview.index(name="articles")
    ```
  </Accordion>

  <Accordion title="Upsert documents">
    ```python theme={null}
    NAMESPACE = 'example-namespace'

    docs = [
        {
            "_id": "doc1",
            "title": "Machine learning in 2024",
            "body": "Machine learning models are revolutionizing natural language processing",
            "category": "technology",
            "year": 2024,
        },
        {
            "_id": "doc2",
            "title": "Vector databases",
            "body": "Vector databases enable fast similarity search across embeddings",
            "category": "technology",
            "year": 2023,
        },
        {
            "_id": "doc3",
            "title": "Quantum computing",
            "body": "Quantum computers leverage superposition for faster computation",
            "category": "science",
            "year": 2024,
        },
    ]

    # batch_upsert splits docs into parallel requests — use it for large sets.
    # For small batches (≤1000 docs), index.documents.upsert(namespace=..., documents=...) is simpler.
    index.documents.batch_upsert(
        namespace=NAMESPACE,
        documents=docs,
        batch_size=50,
        max_concurrency=4,
        show_progress=True,
    )
    ```
  </Accordion>

  <Accordion title="Search — token match (type: text)">
    ```python theme={null}
    NAMESPACE = 'example-namespace'

    response = index.documents.search(
        namespace=NAMESPACE,
        top_k=10,
        score_by=[
            {
                "type": "text",
                "field": "body",
                "query": "machine learning",
            }
        ],
        include_fields=["title", "body", "category", "year"],
    )
    for match in response.matches:
        print(match._id, match._score, getattr(match, "title", ""))
    ```
  </Accordion>

  <Accordion title="Search — Lucene query string (type: query_string)">
    ```python theme={null}
    NAMESPACE = 'example-namespace'

    response = index.documents.search(
        namespace=NAMESPACE,
        top_k=10,
        score_by=[
            {
                "type": "query_string",
                "query": "title:(quantum) OR body:(machine learning)",
            }
        ],
        include_fields=["title", "body"],
    )
    ```
  </Accordion>

  <Accordion title="Search — dense vector ranking with phrase-match filter">
    ```python theme={null}
    NAMESPACE = 'example-namespace'
    query_vector = [0.12, 0.34, ...]  # replace with your actual query vector

    response = index.documents.search(
        namespace=NAMESPACE,
        top_k=10,
        score_by=[
            {
                "type": "dense_vector",
                "field": "embedding",
                "values": query_vector,
            }
        ],
        filter={"body": {"$match_phrase": "machine learning"}},
        include_fields=["title", "body"],
    )
    ```
  </Accordion>

  <Accordion title="Fetch documents">
    ```python theme={null}
    NAMESPACE = 'example-namespace'

    response = index.documents.fetch(
        namespace=NAMESPACE,
        ids=["doc1", "doc2"],
        include_fields=["title", "body", "category"],
    )
    for doc_id, doc in response.documents.items():
        print(doc_id, getattr(doc, "title", ""))
    ```
  </Accordion>

  <Accordion title="Delete documents">
    ```python theme={null}
    NAMESPACE = 'example-namespace'

    index.documents.delete(namespace=NAMESPACE, ids=["doc1", "doc2"])

    index.documents.delete(namespace=NAMESPACE, delete_all=True)
    ```

    Delete is **ID-only** (or `delete_all`) — it does not accept a `filter`. To delete documents matching a metadata expression, search first to get IDs, then pass them to `delete`.
  </Accordion>
</AccordionGroup>

## Bulk import

Bulk import loads large numbers of documents into an index from object storage (Amazon S3, Google Cloud Storage, or Azure Blob Storage) in a single asynchronous job. It is the most efficient way to populate an index with many documents at once. For small or ongoing writes, use [`documents.upsert`](#data-plane-operations) instead.

For indexes with document schemas, import files are [JSON Lines](https://jsonlines.org/) (`.jsonl`), optionally gzip-compressed (`.jsonl.gz`). This is the equivalent of the Parquet-based [Import records](/guides/index-data/import-data) flow used by indexes without a schema definition: the `start_import`, `describe_import`, `list_imports`, and `cancel_import` operations are identical, and Pinecone selects the file format automatically from the index type.

<Note>
  Bulk import is supported for indexes with document schemas in which every field is caller-supplied — full-text `string`, `dense_vector`, `sparse_vector`, and auto-indexed metadata. Semantic-text (auto-embedded) fields are not yet supported in schema.
</Note>

### File format

Each line of a `.jsonl` (or `.jsonl.gz`) file is one JSON document, identical in shape to a document you would pass to [`documents.upsert`](#data-plane-operations). Import validates every document through the same code path as a live upsert, so any document that upserts cleanly imports cleanly.

For example, consider an index whose schema declares one full-text field and one dense vector field:

```json theme={null}
{
  "schema": {
    "fields": {
      "body": {
        "type": "string",
        "full_text_search": { "language": "en" }
      },
      "embedding": {
        "type": "dense_vector",
        "dimension": 3,
        "metric": "cosine"
      }
    }
  }
}
```

Each line supplies `_id`, the schema-declared fields, and any additional fields you want stored as filterable metadata (`category` and `year` here):

```jsonl theme={null}
{"_id": "doc1", "body": "Machine learning models are revolutionizing natural language processing", "embedding": [0.12, 0.34, 0.56], "category": "technology", "year": 2024}
{"_id": "doc2", "body": "Vector databases enable fast similarity search across embeddings", "embedding": [0.91, 0.05, 0.44], "category": "technology", "year": 2023}
```

Each document follows these rules:

* `_id` is required in every document: a non-empty string, unique within the namespace.
* Searchable fields declared in the schema are encoded by type:
  * A `dense_vector` field (`embedding` above) is a JSON array of floats whose length equals the schema's declared `dimension`. When the schema declares a dense vector field, every document must include it.
  * A `sparse_vector` field is an object `{"indices": [...], "values": [...]}`.
  * A full-text `string` field (`body` above) is a JSON string.
* Any other field (`category` and `year` above) is stored on the document and [auto-indexed as filterable metadata](#metadata-fields): a string, number, boolean, or array of strings. An array of numbers in an undeclared field is rejected rather than stored as metadata.
* Field names must not start with `_` (reserved for system fields like `_id`) or `$` (reserved for filter operators).

The same per-document size limits as [upsert](#data-plane-operations) apply.

### Directory layout

Lay files out by namespace, exactly as for [Parquet imports](/guides/index-data/import-data#prepare-your-data): under a common dataset prefix in your bucket or container, create one subdirectory per namespace and place that namespace's `.jsonl` / `.jsonl.gz` files inside it.

```
<BUCKET_OR_CONTAINER_NAME>/
└── <DATASET_PREFIX>/
    ├── namespace1/
    │   ├── 0.jsonl
    │   └── 1.jsonl.gz
    └── namespace2/
        └── 0.jsonl
```

* Each namespace must **not already exist** in the index — imports only create new namespaces.
* A namespace subdirectory can mix plain `.jsonl` and gzip-compressed `.jsonl.gz` files.

### Prepare a file

Generate a schema-conformant `.jsonl` (or `.jsonl.gz`) file from your documents, then upload it to a namespace subdirectory in object storage.

```python Python theme={null}
import gzip
import json

documents = [
    {
        "_id": "doc1",
        "body": "Machine learning models are revolutionizing natural language processing",
        "embedding": [0.12, 0.34, 0.56],   # must match the schema dimension
        "category": "technology",
        "year": 2024,
    },
    {
        "_id": "doc2",
        "body": "Vector databases enable fast similarity search across embeddings",
        "embedding": [0.91, 0.05, 0.44],
        "category": "technology",
        "year": 2023,
    },
]

# Plain JSONL: one compact JSON document per line.
with open("0.jsonl", "w") as f:
    for doc in documents:
        f.write(json.dumps(doc) + "\n")

# Or gzip-compressed (.jsonl.gz) to cut storage and transfer.
with gzip.open("0.jsonl.gz", "wt") as f:
    for doc in documents:
        f.write(json.dumps(doc) + "\n")
```

Upload the file to the relevant namespace subdirectory in your bucket or container, e.g. `<DATASET_PREFIX>/namespace1/0.jsonl`.

#### Convert Parquet files to JSONL

If your data is already stored as Parquet in the [vector import format](/guides/index-data/import-data#prepare-your-data) (`id`, `values`, `sparse_values`, `metadata` columns), convert each file to JSONL for the document schema. Map `id` to `_id`, the vector columns to your schema's field names, and spread the `metadata` JSON string into top-level fields:

```python Python theme={null}
import gzip
import json

import pyarrow.parquet as pq

# Your schema's field names
DENSE_FIELD = "embedding"          # dense_vector field
SPARSE_FIELD = "sparse_embedding"  # sparse_vector field

table = pq.read_table("0.parquet")

with gzip.open("0.jsonl.gz", "wt") as f:
    for row in table.to_pylist():
        doc = {"_id": row["id"]}
        if row.get("values") is not None:
            doc[DENSE_FIELD] = row["values"]
        if row.get("sparse_values") is not None:
            doc[SPARSE_FIELD] = {
                "indices": row["sparse_values"]["indices"],
                "values": row["sparse_values"]["values"],
            }
        if row.get("metadata"):
            # Metadata keys become top-level fields. Keys that match a
            # schema-declared field (e.g. a full-text "body" field) are
            # validated against the schema; the rest are auto-indexed metadata.
            doc.update(json.loads(row["metadata"]))
        f.write(json.dumps(doc) + "\n")
```

### Start an import

To import from a secure data source, you first need a [storage integration](/guides/operations/integrations/manage-storage-integrations) that gives Pinecone access to your object storage. An integration is not required for public data sources.

Start the import against the index host with the [`start_import`](/reference/api/latest/data-plane/start_import) operation (`POST /bulk/imports`) — the same endpoint, parameters, and behavior as for [Parquet imports](/guides/index-data/import-data#import-records-into-an-index). Pinecone detects from the index's document schema that the files are JSONL. For `uri`, specify the bucket or container in your storage provider's URI format, plus the dataset prefix — not a path to a single file or a namespace subdirectory.

<Note>
  Bulk import is not yet supported in any Pinecone SDK. Use the REST API to start and manage imports.
</Note>

```bash curl theme={null}
# To get the unique host for an index, see
# https://docs.pinecone.io/guides/manage-data/target-an-index
PINECONE_API_KEY="YOUR_API_KEY"
INDEX_HOST="INDEX_HOST"

curl "https://$INDEX_HOST/bulk/imports" \
  -H "Api-Key: $PINECONE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Pinecone-Api-Version: 2026-01.alpha" \
  -d '{
    "integrationId": "a12b3d4c-47d2-492c-a97a-dd98c8dbefde",
    "uri": "STORAGE_URI/DATASET_PREFIX",
    "errorMode": { "onError": "continue" }
  }'
```

The response contains an `id` you can use to track the import with the [`describe_import`](/reference/api/latest/data-plane/describe_import) operation:

```json Response theme={null}
{
  "id": "1"
}
```

Imported documents are indexed asynchronously and may not be searchable immediately after the import reports complete.

### Track and manage an import

The [`describe_import`](/reference/api/latest/data-plane/describe_import), [`list_imports`](/reference/api/latest/data-plane/list_imports), and [`cancel_import`](/reference/api/latest/data-plane/cancel_import) operations behave the same for document and vector indexes. See [Import records](/guides/index-data/import-data#track-import-progress) for the full request and response shapes and troubleshooting.

```bash curl theme={null}
curl -X GET "https://$INDEX_HOST/bulk/imports/1" \
  -H "Api-Key: $PINECONE_API_KEY" \
  -H "X-Pinecone-Api-Version: 2026-01.alpha"
```

Per-document errors identify the file name, row number, and document `_id`. With `errorMode.onError` set to `continue`, invalid documents are skipped and the rest import — use `records_imported` to see how many loaded; with `abort`, the import stops on the first invalid document.

A namespace subdirectory that contains no `.jsonl` / `.jsonl.gz` files is skipped — no namespace is created for it. An import that finds no importable files anywhere under the dataset prefix fails.

### Import limits

Document imports share the [import limits](/guides/index-data/import-data#import-limits): up to 10,000 namespaces and 100,000 files per import, up to 10 GB per file, and — for on-demand indexes — up to 1 TB total input data per import.

For `.jsonl.gz` files, size limits are checked against an estimated uncompressed size of 10× the compressed file size, so plan for roughly 1 GB per compressed file.

## Tokens and analyzers

The word "token" appears in every scoring method, but it means different things in each. Knowing what counts as a token in your chosen method is essential to writing queries that match what you expect.

### FTS tokens (`type: "text"`, `type: "query_string"`, and `$match_*` filters)

When you declare a field with `full_text_search: { ... }`, Pinecone runs the field's text through an **analyzer pipeline** at index time and at query time. Both `type: "text"` and `type: "query_string"` use the same pipeline, and the text-match filter operators ([`$match_phrase`, `$match_all`, `$match_any`](#filters-vs-scoring)) reuse it as well — so a token that scores in BM25 will match in a filter on the same field.

The pipeline (in order):

1. **Split** the text on whitespace and punctuation. Hyphenated words become multiple tokens (`state-of-the-art` → `state`, `of`, `the`, `art`).
2. **Lowercase** every token. Lowercasing is server-applied and cannot be overridden.
3. **Stem** each token to its root form, if [`stemming`](#stemming) is enabled on the field. The stemmer is selected by the field's [`language`](#language) setting (`models` → `model`, `running` → `run`).
4. **Drop stop words** (common words like `the`, `and`), if `stop_words: true` is set on the field. Not all languages have built-in stop word lists; see the [Language](#language) table for details.
5. **Cap** each token at 40 characters. This cap is server-applied and cannot be overridden.

For example, with the `english` analyzer, `stemming: true`, and `stop_words: false`, the input `"State-of-the-Art Models"` becomes the tokens `state`, `of`, `the`, `art`, `model`. Those are the tokens BM25 scores against, and the tokens a `$match_phrase: "art models"` filter will look for.

Fields configured for [substring search](#substring-search-with-n-grams) replace this whole-token pipeline with character n-gram tokenization, so a token is further split into overlapping character sequences.

### Dense-vector tokens (`type: "dense_vector"`)

Dense embedding models have their own internal tokenizer — usually a subword scheme like BPE, WordPiece, or SentencePiece — that breaks text into pieces the model was trained on. Those tokens are **private to the model**. You never query them directly: a dense search compares the full embedding of a query against the full embedding of a document. The same string can therefore behave very differently in `type: "text"` (which sees the FTS analyzer tokens above) and `type: "dense_vector"` (which sees a single high-dimensional vector). The `$match_*` filter operators do not apply to dense-vector fields.

### Sparse-vector tokens (`type: "sparse_vector"`)

Sparse encoders also tokenize internally, and the tokenization depends on the encoder. Pinecone's hosted [`pinecone-sparse-english-v0`](/models/pinecone-sparse-english-v0) produces learned per-token weights and **expands to related terms** that don't appear in the source text. Encoder tokens are not interchangeable with FTS analyzer tokens, and `$match_*` filters do not apply to sparse-vector fields.

### Practical implication

If your application stores the same source text in an FTS-enabled `string` field and also encodes it into a `dense_vector` or `sparse_vector` field, the three representations are tokenized **independently**: the FTS analyzer for the `string` field, and each model's internal tokenizer for the vector fields. Identical query strings will therefore retrieve different documents under different `score_by` types, and `$match_*` filters can only narrow on the FTS-analyzer tokens of FTS-enabled `string` fields.

## Query syntax reference

Full-text search supports two text-based query types with different capabilities:

| Feature                 | `type: "text"`                                                             | `type: "query_string"`                                 |
| ----------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------ |
| **Purpose**             | Simple token search on one field                                           | Lucene query syntax                                    |
| **`fields` parameter**  | Required (exactly one field)                                               | Optional (restricts to listed text-searchable fields)  |
| **Multi-word behavior** | Token match, OR across terms (BM25)                                        | OR by default; use `AND`, quotes, etc. for other logic |
| **Boolean operators**   | Not supported (treated as words)                                           | `AND`, `OR`, `NOT`, `+`, `-`                           |
| **Phrase prefix**       | Not supported                                                              | `"phrase pre"*` (last term as prefix)                  |
| **Phrase matching**     | Not supported in `score_by` (use `query_string` or `$match_phrase` filter) | Wrap in quotes: `"exact phrase"`                       |
| **Phrase slop**         | Not supported                                                              | `"phrase"~N`                                           |
| **Boosting**            | Not supported                                                              | `term^N`                                               |
| **Regex**               | Not supported                                                              | `field:/pattern.*/`                                    |
| **Fuzzy matching**      | Not supported                                                              | `term~`, `term~N` (typo tolerance)                     |
| **Stemming**            | Supported ([when enabled](#stemming))                                      | Supported ([when enabled](#stemming))                  |
| **Case sensitivity**    | Case-insensitive                                                           | Case-insensitive                                       |

### Token matching (`type: "text"`)

With `type: "text"`, the query string is run through the field's analyzer pipeline (see [Tokens and analyzers](#tokens-and-analyzers)) and each resulting term contributes to the BM25 score. Multiple terms use **OR** semantics: documents can match if they contain **any** of the terms; documents that match more terms or stronger term statistics typically rank higher. Matching is case-insensitive. Exact **phrase** constraints (adjacent words in order) belong in `type: "query_string"` using quotes, or in a `$match_phrase` filter.

| Query              | Matches                                                               | Does not match                         |
| ------------------ | --------------------------------------------------------------------- | -------------------------------------- |
| `machine learning` | "**Machine** learning is great" (has "machine")                       | "Vector databases only" (neither term) |
| `machine learning` | "We use **learning** and **machine**" (both terms present, any order) | "Vector databases only" (neither term) |
| `machine`          | "**Machine** learning is great"                                       | "Vector databases only" (no "machine") |

**Key behaviors:**

* **Single term** (`machine`): Matches documents containing that term. Case-insensitive.
* **Multiple terms** (`machine learning`): Each term is searched independently with OR-style matching and combined BM25 scoring — not as a single adjacent phrase.
* **No operator support**: Characters like `AND`, `OR`, `NOT`, `*`, `~`, `^`, `+`, `-`, and quotes are treated as literal text.

### Lucene query syntax (`type: "query_string"`)

With `type: "query_string"`, you write Lucene query syntax, with operator support. Field names are embedded in the query itself (e.g., `content:(term)`) and can combine multiple fields with boolean operators.

| Operator       | Syntax                     | Example                             | Description                                                 |
| -------------- | -------------------------- | ----------------------------------- | ----------------------------------------------------------- |
| Term           | `field:(word)`             | `body:(computers)`                  | Match documents containing term                             |
| Multiple terms | `field:(a b)`              | `body:(machine learning)`           | OR by default — matches either term                         |
| Phrase         | `field:("words")`          | `body:("machine learning")`         | Exact phrase match (adjacent, in order)                     |
| AND            | `AND`                      | `body:(a AND b)`                    | Both terms required                                         |
| OR             | `OR`                       | `body:(a OR b)`                     | Either term matches (same as default)                       |
| NOT            | `NOT`                      | `body:(a NOT b)`                    | Exclude second term                                         |
| Required       | `+term`                    | `body:(+database search)`           | Term must be present                                        |
| Excluded       | `-term`                    | `body:(database -deprecated)`       | Term must not be present                                    |
| Grouping       | `(expr)`                   | `body:((a OR b) AND c)`             | Control precedence                                          |
| Phrase slop    | `"phrase"~N`               | `body:("fast search"~2)`            | Allow up to N words between phrase terms                    |
| Boost          | `term^N`                   | `body:(machine^3 learning)`         | Multiply term's relevance score by N                        |
| Phrase prefix  | `"phrase pre"*`            | `body:("james w"*)`                 | Last term in phrase matched as prefix                       |
| Regex          | `field:/pattern.*/`        | `body:/comput.*/`                   | Match documents by regular expression on a field            |
| Fuzzy          | `term~` or `term~N`        | `body:(compxter~1)`                 | Match terms within edit distance N (0–2) for typo tolerance |
| Cross-field    | `fieldA:(…) OR fieldB:(…)` | `title:(quantum) OR body:(machine)` | Combine clauses across text-searchable fields               |

<AccordionGroup>
  <Accordion title="Terms and default OR behavior">
    A **term** is a single word. Multiple space-separated terms use **OR logic** by default.

    ```
    body:(machine learning)
    ```

    Matches documents containing "machine" OR "learning" (or both). Documents with both terms rank higher.
  </Accordion>

  <Accordion title="Phrases">
    Wrap multiple words in quotes to match them as an exact sequence.

    ```
    body:("machine learning")
    ```

    Matches only documents containing the exact phrase "machine learning" with the words adjacent. That is different from `type: "text"` with `query: "machine learning"`, which uses **token OR** matching on the field. For phrase matching as a **filter** (e.g., composed with dense-vector ranking), use `{"body": {"$match_phrase": "machine learning"}}` in the `filter` block.

    *Phrase terms are matched against the field's analyzed tokens. If [stemming](#stemming) is enabled on the field, the phrase terms stem too — e.g., `"running fast"` matches `running fast` and `runs fast`.*
  </Accordion>

  <Accordion title="Boolean operators (AND, OR, NOT)">
    Use `AND`, `OR`, and `NOT` for explicit boolean logic.

    ```
    body:(machine AND learning)        # Both terms required (any order)
    body:(machine OR learning)         # Either term (same as default)
    body:(machine NOT learning)        # "machine" but not "learning"
    ```

    **Precedence:** AND binds tighter than OR. Use parentheses to control order:

    ```
    body:((database OR storage) AND distributed)
    ```
  </Accordion>

  <Accordion title="Required and excluded terms (+, -)">
    Use `+` to require a term and `-` to exclude a term.

    ```
    body:(+database distributed)       # MUST contain "database", "distributed" optional
    body:(database -deprecated)        # Contains "database", must NOT contain "deprecated"
    body:(+vector +search -legacy)     # MUST have "vector" AND "search", must NOT have "legacy"
    ```
  </Accordion>

  <Accordion title="Phrase proximity (slop)">
    Allow words in a phrase to appear within N positions of each other.

    ```
    body:("machine learning"~3)
    ```

    Matches "machine learning", "machine deep learning", or "machine-assisted learning" (words within 3 positions).

    *The phrase terms are matched against analyzed tokens, so [stemming](#stemming) (when enabled on the field) applies here too.*
  </Accordion>

  <Accordion title="Term boosting">
    Increase the importance of specific terms in ranking using `^N`.

    ```
    body:(machine^3 learning)          # "machine" weighted 3x more than "learning"
    body:("neural network"^2 deep)     # Phrase boosted 2x
    ```

    Documents with boosted terms rank higher when those terms appear.
  </Accordion>

  <Accordion title="Phrase prefix">
    Append `*` to a quoted phrase to treat the last term as a prefix. The phrase must contain at least two terms.

    ```
    body:("james w"*)                  # Matches "james webb", "james watson", "james wilde"
    body:("machine lea"*)              # Matches "machine learning", "machine learns"
    ```

    Both the literal terms and the prefix are matched against the field's analyzed tokens. If [stemming](#stemming) is enabled on the field, stemming applies to the completed terms in the phrase, while the final prefix is expanded against analyzed tokens.

    Phrase prefix is optimized for autocomplete-style queries where the final word prefix is reasonably specific. To keep latency low, Pinecone expands the final prefix to the first 50 matching terms in lexicographic order. For example, `"new yor"*` can match `new york`, but `"new yo"*` might not if `york` is not among the first 50 expanded terms for `yo`.
  </Accordion>

  <Accordion title="Regex">
    Wrap a pattern in forward slashes to match documents by regular expression on a field.

    ```
    body:/comput.*/
    ```

    Matches documents whose `body` field contains a token matching the regex `comput.*` (e.g., "computer", "computing", "computation"). Regex patterns are matched against individual analyzed tokens, not the raw field text.

    ```
    body:/machin[ei].*/
    ```

    Matches tokens like "machine" or "machene". Standard Lucene regex syntax is supported.

    Regex is only available with `type: "query_string"`. It is not supported with `type: "text"`.
  </Accordion>

  <Accordion title="Fuzzy matching (typo tolerance)">
    Append `~` to a bare term to match indexed terms within a small edit distance, so a misspelled query term still matches the intended word.

    ```
    body:(compxter~1)                  # Matches "computer" (1 edit away)
    body:(machine~ learning~)          # Auto distance per term, based on term length
    title:(pinecone~2)                 # Explicit distance 2
    ```

    * **`term~`** — automatic distance based on the term's length: terms shorter than 4 characters must match exactly, terms of 4–7 characters allow 1 edit, and terms of 8 or more characters allow 2 edits.
    * **`term~N`** — fixed edit distance `N`, where `N` is `0`, `1`, or `2`. `~0` is an exact match. A distance greater than 2 is a query error (`400`).

    An "edit" is an inserted, deleted, or substituted character (plain Levenshtein distance). Swapping two adjacent characters counts as 2 edits. Matching is case-insensitive, as with all text queries.

    Fuzzy matches are scored as a constant; exact matches still contribute their full BM25 score, so an exact hit ranks above a fuzzy hit for the same term. Fuzzy composes with the rest of the query syntax — boolean operators, required/excluded terms, boosts, field qualifiers, and metadata filters.

    <Note>
      The `~` operator is fuzzy only when it follows a **bare term**. After a quoted phrase, `~N` keeps its [phrase slop](#query-syntax-reference) meaning — for example, `body:("machine learning"~2)` is slop, while `body:(learning~2)` is fuzzy. There is no fuzzy phrase matching.
    </Note>

    <Note>
      On [stemmed](#stemming) fields, fuzzy matching runs against the stemmed terms and is best-effort: a typo that changes how a word stems may not match. Fuzzy matching is most effective on fields without stemming (the default). Fuzzy is available only with `type: "query_string"`; with `type: "text"`, `~` is treated as a literal character.
    </Note>
  </Accordion>

  <Accordion title="Cross-field queries">
    `query_string` can target multiple fields in the same expression. Use Lucene field qualifiers (`field:(clause)`) directly in the query string; omit them to run against all text-searchable fields:

    ```
    title:(quantum) OR body:(machine learning)
    ```

    Matches documents whose `title` contains "quantum", documents whose `body` contains "machine" or "learning", or both — with BM25 scoring combining across fields.
  </Accordion>
</AccordionGroup>

## Stemming

Stemming reduces words to their root form so that morphological variants match each other. For example, with stemming enabled, a query for "run" also matches documents containing "running" or "runs".

Stemming is **opt-in** and disabled by default. To enable it, set `stemming: true` on a text-searchable field when creating the index. The stemming algorithm is determined by the field's [`language`](#language) setting.

**Example: enabling stemming with French**

```json theme={null}
{
  "schema": {
    "fields": {
      "body": {
        "type": "string",
        "full_text_search": {
          "stemming": true,
          "language": "french"
        }
      }
    }
  }
}
```

Stemming applies to both `type: "text"` and `type: "query_string"` queries on the field.

<Note>
  Stemming is set at index creation and cannot be changed afterward.
</Note>

## Language

The `language` parameter controls tokenization and stemming behavior for a text-searchable field. It determines how text is analyzed during indexing and search: how words are split into tokens and, when [stemming](#stemming) is enabled, which language-specific rules are used to reduce words to their root forms.

The default language is `"en"` (English). You can specify a language using either its short code or full name (e.g., `"fr"` or `"french"`).

**Supported languages:**

| Code | Full name    | Stop words |
| ---- | ------------ | ---------- |
| `ar` | `arabic`     | No         |
| `da` | `danish`     | Yes        |
| `de` | `german`     | Yes        |
| `el` | `greek`      | No         |
| `en` | `english`    | Yes        |
| `es` | `spanish`    | Yes        |
| `fi` | `finnish`    | Yes        |
| `fr` | `french`     | Yes        |
| `hu` | `hungarian`  | Yes        |
| `it` | `italian`    | Yes        |
| `nl` | `dutch`      | Yes        |
| `no` | `norwegian`  | Yes        |
| `pt` | `portuguese` | Yes        |
| `ro` | `romanian`   | No         |
| `ru` | `russian`    | Yes        |
| `sv` | `swedish`    | Yes        |
| `ta` | `tamil`      | No         |
| `tr` | `turkish`    | No         |

<Note>
  Language is set at index creation and cannot be changed afterward.
</Note>

## Substring search with n-grams

By default, full-text search matches whole tokens: a query for `comp` does not match a document containing `computer`. To match substrings (for example, to find `computer` from `comp`, `mput`, or `uter`), configure a text field for **character n-gram** tokenization.

With n-gram tokenization, each token is broken into overlapping character sequences (n-grams) at index time, and query text is broken the same way at search time, so a substring of an indexed word matches. This is useful for partial-word matching, autocomplete, and searching identifiers or codes where users type only a fragment.

To enable it, set an `ngram` object on a text field's `full_text_search` config at index creation:

```json theme={null}
{
  "schema": {
    "fields": {
      "product_name": {
        "type": "string",
        "full_text_search": {
          "ngram": {
            "min_gram": 3,
            "max_gram": 4,
            "prefix_only": false
          }
        }
      }
    }
  }
}
```

`ngram` parameters:

| Parameter     | Type    | Required             | Description                                                                                                                                                                                                         |
| ------------- | ------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `min_gram`    | integer | Yes                  | Shortest n-gram to generate. Must be at least `1`.                                                                                                                                                                  |
| `max_gram`    | integer | Yes                  | Longest n-gram to generate. Must be at least `min_gram` and at most `10`.                                                                                                                                           |
| `prefix_only` | boolean | No (default `false`) | When `true`, generate only n-grams anchored to the start of each token (edge n-grams). Use this for prefix and autocomplete matching. When `false`, generate n-grams at every position for full substring matching. |

For example, with `min_gram: 3`, `max_gram: 4`, and `prefix_only: false`, the token `search` is indexed as `sea`, `ear`, `arc`, `rch`, `sear`, `earc`, `arch`. A shorter or longer window changes the tradeoff: smaller n-grams match more loosely and grow the index more; larger n-grams are more precise but require longer matching substrings.

**Querying an n-gram field.** No special query syntax is needed. Once a field is configured for n-grams, ordinary `type: "text"` and `query_string` queries against it match on substrings automatically, because the query text is tokenized into the same n-grams as the indexed text:

```python Python theme={null}
response = index.documents.search(
    namespace="example-namespace",
    top_k=10,
    score_by=[
        {
            "type": "text",
            "field": "product_name",
            "query": "sear",
        }
    ],
    include_fields=["product_name"],
)
```

<Note>
  N-gram tokenization cannot be combined with [`stemming`](#stemming) or `stop_words` on the same field — an index-creation request that sets `ngram` alongside either is rejected with a `400` error. Tokens are always lowercased. Because every position emits a token for each gram length, an n-gram field is larger on disk than a plain text field; keep `min_gram`/`max_gram` as narrow as your matching needs allow.
</Note>

<Note>
  N-gram configuration is set at index creation and cannot be changed afterward.
</Note>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Document not appearing in search results">
    * Check indexing latency: new documents may take up to 1 minute to become searchable; schemas with multiple indexed fields may take slightly longer.
    * Verify the upsert response shows the expected `upserted_count`.
    * Confirm you're searching the same namespace where you upserted.
    * With `type: "text"`, multi-word queries use **token OR** matching — documents need not contain the full phrase. Try a single-term query first to confirm the document is searchable.
    * If using filters, ensure the document's field values match your filter conditions. Metadata fields are auto-indexed at upsert time, so any field present on a document can be filtered on; filtering on a field that no document contains returns no results.
  </Accordion>

  <Accordion title="Unexpected search results">
    * **`type: "text"` uses OR across terms.** `machine learning` matches documents that contain "machine", "learning", or both (BM25 ranking). For an **exact phrase**, use `type: "query_string"` with `body:("machine learning")` or a `$match_phrase` filter.
    * **`type: "query_string"` defaults to OR for unquoted terms.** `body:(machine learning)` matches documents containing either term. Use `AND` or `+` for required terms.
    * Operators like `AND`, `OR`, `NOT`, `*`, `~`, and `^` only work with `type: "query_string"`. With `type: "text"`, they are treated as literal words.
  </Accordion>

  <Accordion title="Query syntax errors">
    Query syntax errors only apply to `type: "query_string"`. With `type: "text"`, any input is valid as a literal string to be tokenized.

    * Unmatched quotes (`"machine learning`): Close all quotes.
    * Empty query: Provide at least one search term.
    * Invalid boolean syntax (`AND machine`): Operators need terms on both sides.
    * Unbalanced parentheses: Match all opening and closing parens.
    * Unknown field name: Field names in the query must match text-searchable fields in the schema.
  </Accordion>

  <Accordion title="API errors">
    * `401 Unauthorized`: Check the `Api-Key` header.
    * `400 Bad Request`: Check JSON syntax and required fields. Examples: `fields` array with more than one element for `text`/`dense_vector`/`sparse_vector`; missing mutually-exclusive field for Fetch/Delete.
    * `404 Not Found`: Verify the index name and host URL.
    * Missing API version: Add `X-Pinecone-Api-Version: 2026-01.alpha`.
  </Accordion>

  <Accordion title="Upsert errors">
    * Type mismatch: Ensure values match declared schema types.
    * Invalid `_id`: Every document must have a non-empty `_id` string.
    * Reserved names: Field names cannot start with `_` (reserved for system-managed fields like `_id` and `_score`) or `$` (reserved for filter operators), and must be at most 64 bytes.
  </Accordion>

  <Accordion title="Slow search performance">
    * Reduce query complexity: Boolean operators and large phrase slop are more expensive than simple term queries.
    * Simplify filters: Filters are applied before scoring, so broad filters increase the search space.
    * For cost-sensitive workloads, use `read_capacity.mode: "Dedicated"` to get predictable latency.
  </Accordion>

  <Accordion title="Common request-shape pitfalls">
    When a request is rejected with a 4xx that doesn't seem to match your intent, the cause is usually one of these:

    * **Sparse-vector `score_by` clauses use `sparse_values`, not `values`.** The `values` key is for `dense_vector`. A sparse clause needs the full object: `"sparse_values": { "indices": [...], "values": [...] }`.

    * **Every `score_by` clause must include `type`.** It's the discriminator that selects the scoring method (`text`, `query_string`, `dense_vector`, `sparse_vector`). Omitting it returns a 400.

    * **Every document must have a non-empty `_id` string.** There is no default; the upsert request fails if any document in the batch is missing `_id` or has an empty value.

    * **Wait for `status.ready: true` before searching.** A newly created index can briefly return empty results. For `Dedicated` read capacity, also wait for `read_capacity.status.state: "Ready"`.

    * **The match-score response field is `_score`, not `score`.** A user metadata field named `score` is allowed and is returned alongside the system-owned `_score`.

    * **Namespace is part of the URL path.** Use `__default__` (the literal string) if you don't need partitioning. An empty path segment is rejected.

    * **`dense_vector` queries use `values`, not `query`.** Only `text` and `query_string` clauses use `query` (a string). `dense_vector` and `sparse_vector` use `values` (a float array) and `sparse_values` (an `{indices, values}` object) respectively.
  </Accordion>
</AccordionGroup>

## Public preview

Full-text search is in public preview under API version `2026-01.alpha`. The feature is ready for production evaluation; APIs may continue to evolve before general availability.

**Requirements & limitations**

* All requests require `X-Pinecone-Api-Version: 2026-01.alpha`.
* The REST API, Python SDK (`pinecone`, `pc.preview.*` namespace for FTS control plane), and Pinecone console are the supported entry points for public preview.
* **Endpoint compatibility**: indexes with document schemas use the `/namespaces/{namespace}/documents/*` endpoints; dense, sparse, and integrated-inference indexes continue to use `/vectors/*` (and `/records/*` for integrated inference). The two endpoint families are index-type-specific and don't cross over.
* Supported deployment modes: managed (serverless) with `read_capacity.mode` of `OnDemand` or `Dedicated`.
* Changing an index from dedicated read capacity back to on-demand read capacity is not supported. To move from dedicated read capacity to on-demand, create a new on-demand index and reingest your data.
* Schemas declare ranking fields only: text fields (`string` with `full_text_search`), `dense_vector`, and `sparse_vector`. Text-only, text + dense vector, and combined dense + sparse + text schemas are all supported in a single index. Metadata-only field declarations (`string` without `full_text_search`, `string_list`, `float`, `boolean`) are rejected at index creation; metadata is auto-indexed at upsert time.
* **Schema and document limits**: a schema can contain up to 100 `full_text_search` string fields; each `full_text_search` string field can be up to 100 KB and 10,000 tokens; tokens can be up to 256 bytes before analyzer truncation; each document can be up to 2 MB; each upsert request can contain up to 1000 documents and 2 MB.
* **Metadata size**: metadata fields on a document (everything outside FTS-enabled `string` fields) are limited to 40 KB per document in total. This limit does not apply to `full_text_search` text fields.
* **Vector-field cardinality**: a schema can declare up to 100 `string` fields with `full_text_search` enabled, but at most one `dense_vector` field and at most one `sparse_vector` field per index.
* **Field-name policy**: schema and metadata field names must not start with `_` (reserved for system-managed fields like `_id` and `_score`) or `$` (reserved for filter operators), and are limited to 64 bytes.
* The match-score response field is `_score` (renamed from `score` so that user metadata named `score` can coexist with the system-owned match score in the flat response payload).
* **A single search request ranks by one scoring type.** Multi-field BM25 is supported: pass multiple `text` clauses (one per field) or a single `query_string` clause that targets several fields — every contributing field weighs equally in `2026-01.alpha`; there is no per-clause weight parameter. To combine BM25 ranking with `dense_vector` or `sparse_vector` ranking, restrict the dense (or sparse) search with a text-match filter (`$match_phrase`, `$match_all`, `$match_any`) on the lexical field, or run separate searches and merge the results client-side.
* Newly upserted documents are indexed asynchronously and may not be searchable immediately.
* **No partial / per-field updates**: `POST /namespaces/{namespace}/documents/upsert` always replaces the entire document for a given `_id`. There is no `PATCH` endpoint and no field-level merge in `2026-01.alpha`. To update a single field, fetch the document by ID (`POST /namespaces/{namespace}/documents/fetch`), modify the field client-side, and upsert the full document back under the same `_id`. Field-level merge is on the roadmap for a post-public-preview release.
* **Schemas are fixed at index creation.** Adding, removing, or retyping fields after creation is not yet supported. Existing pre-public-preview indexes cannot be backfilled with a schema — to use FTS, dense + FTS, or any document API query in `2026-01.alpha`, create a new index with the desired schema and reindex documents.
* **Metadata is auto-indexed**: any field on an upserted document that is not declared in the schema is automatically indexed for filtering. The schema declares only ranking fields (FTS-enabled `string`, `dense_vector`, `sparse_vector`); declaring metadata-only fields (`string` without `full_text_search`, `string_list`, `float`, `boolean`) is rejected at index creation. Track metadata field names and types in your application — Pinecone infers the type from the values you upsert.
* **Bulk import** from object storage is supported for indexes with document schemas via JSONL files — see [Bulk import](#bulk-import). Semantic-text (auto-embedded) fields are not yet supported in schemas.
* **Maximum results per query**: `top_k` is capped at **10,000**. Full-text search is optimized for ranked retrieval; for aggregation- or count-style queries (e.g., "how many documents contain term X"), faceting is on the roadmap for a future release.
* Indexes cannot be created in CMEK-enabled projects.
* Backup and restore are not yet supported.
* **`describe_index_stats`** is not yet supported on indexes with document schemas.
* [Fuzzy matching](#query-syntax-reference) (`term~`, `term~N`) is available only in `query_string` scoring, not in `type: "text"` or in `$match_*` filters.
* Single-term prefix wildcards (`auto*`) are not supported; use phrase prefix (`"word auto"*`) instead, or configure a field for [substring search](#substring-search-with-n-grams).

## Pricing

Reads and writes on indexes with document schemas are metered using the same [read units (RUs)](/guides/manage-cost/understanding-cost#read-units) and [write units (WUs)](/guides/manage-cost/understanding-cost#write-units) model as vector indexes. List pricing for public preview will be announced before general availability.

## Next steps

* **[Create an index](/guides/index-data/create-an-index)**: create an index with a document schema that declares your ranking fields.
* **[Model your data](/guides/index-data/data-modeling#schema-patterns)**: schema-pattern recipes for keyword-only, multi-field, dense + FTS, and multi-signal indexes.
* **[Choose a search approach](/guides/search/search-overview)**: compare full-text, semantic, sparse-vector, and hybrid search.
* **[Hybrid search](/guides/search/hybrid-search)**: combine keyword and vector ranking, including when to use a document schema versus the vector API.
* **[Filter by metadata](/guides/search/filter-by-metadata)**: narrow the candidate set before ranking.
* **[Understanding cost](/guides/manage-cost/understanding-cost)**: how read units and write units are metered.


# Hybrid search
Source: https://docs.pinecone.io/guides/search/hybrid-search

Combine dense semantic search with sparse lexical search in a single Pinecone query to improve recall for keyword matches, synonyms, and rare terms.

[Semantic search](/guides/search/semantic-search) and [lexical search](/guides/search/lexical-search) are powerful information retrieval techniques, but each has notable limitations. For example:

* Semantic search can miss results based on exact keyword matches, especially in scenarios involving domain-specific terminology.
* Lexical search can miss results based on relationships, such as synonyms and paraphrases.

To work around these limitations, you can use hybrid search, which combines semantic and lexical search.

<Note>
  This page covers the **vector-API hybrid pattern**: a single index that stores both a dense vector and a sparse vector per record, queried together in one request. For indexes with document schemas, hybrid retrieval is covered in [Full-text search](/guides/search/full-text-search), where one schema declares FTS-enabled `string` (BM25), `dense_vector`, and `sparse_vector` fields side by side and you combine signals with text-match filters or by merging results client-side. For multi-signal indexes that combine dense, sparse, and text fields in a single schema, see the [Multi-signal index pattern](/guides/index-data/data-modeling#schema-patterns). Both patterns are fully supported; pick by data shape (records vs. JSON documents).
</Note>

<Warning>
  When you query a single index that stores both dense and sparse vectors, BM25 scores and `pinecone-sparse-english-v0` sparse-weight outputs are **not normalized** to the dense vector range (cosine `[-1, 1]`). Without explicit weighting, the sparse component dominates the combined score. Before going to production, read [Normalize sparse and dense values](#normalize-sparse-and-dense-values) and apply the `hybrid_score_norm` query-time pattern, or model the workload as an [index with a document schema](/guides/get-started/concepts#document) and combine BM25 with a dense or sparse ranking using a text-match filter (or client-side merge) per [Full-text search](/guides/search/full-text-search).
</Warning>

## Choosing a hybrid pattern

Pinecone supports three hybrid patterns, split by API surface and data shape. Pick the one that matches your data:

| Pattern                                                                                                 | API      | Data shape                                                                        | How signals combine                                                                                                                     | Trade-offs                                                                                                                                  |
| ------------------------------------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| **[Single index for dense and sparse vectors](#use-a-single-index-for-dense-and-sparse-vectors)**       | Vector   | One record carries both a dense and a sparse vector                               | Server-side dotproduct of weighted dense + sparse query vectors                                                                         | Simplest single-request architecture, but BM25/sparse scores are unbounded — requires `alpha` weighting per query. No integrated embedding. |
| **[Separate indexes for dense and sparse vectors](#use-separate-indexes-for-dense-and-sparse-vectors)** | Vector   | Two indexes, linked by shared `_id`                                               | Two queries, merged client-side (e.g., [RRF](/guides/search/reciprocal-rank-fusion))                                                    | More moving parts, but supports sparse-only queries, integrated embedding, and independent reranking per index.                             |
| **[Multi-field document schema](/guides/search/full-text-search)**                                      | Document | One document with `dense_vector` + FTS-enabled `string` fields in the same schema | Either: dense ranking *narrowed* by a text-match filter (`$match_phrase`/`$match_all`/`$match_any`); or two searches merged client-side | Text-centric workloads; no `alpha` tuning needed. Doesn't support integrated embedding in public preview.                                   |

**Rule of thumb:** if your hybrid signal is "I have both vectors per record," reach for a vector-API pattern (single index or separate indexes). If your hybrid signal is "I have text plus an embedding for the same document," reach for the document API (multi-field document schema).

The remainder of this page covers the vector-API patterns. For the document API hybrid pattern, see [Full-text search](/guides/search/full-text-search) and the [multi-signal schema example](/guides/index-data/data-modeling#schema-patterns).

## Hybrid search approaches

There are two ways to perform hybrid search **on the vector API**:

* [Use a single index for dense and sparse vectors](#use-a-single-index-for-dense-and-sparse-vectors). This is the **recommended** approach for most use cases because it provides a simpler architecture with less operational overhead.<br />
  Steps:
  1. [Create the index](#hybrid-single-1-create)
  2. [Generate vectors](#hybrid-single-2-embed)
  3. [Upsert records](#hybrid-single-3-upsert)
  4. [Search the index](#hybrid-single-4-query)
  5. [Search with explicit weighting](#hybrid-single-5-alpha)
* [Use separate indexes for dense and sparse vectors](#use-separate-indexes-for-dense-and-sparse-vectors). This approach provides more flexibility but requires managing two indexes and maintaining linkages between vectors.<br />
  Steps:
  1. [Create the indexes](#hybrid-sep-1-create)
  2. [Upsert vectors](#hybrid-sep-2-upsert)
  3. [Search by dense vectors](#hybrid-sep-3-dense)
  4. [Search by sparse vectors](#hybrid-sep-4-sparse)
  5. [Merge and deduplicate](#hybrid-sep-5-merge)
  6. [Rerank](#hybrid-sep-6-rerank)

The following table summarizes the key differences between the two approaches:

| Approach                         | Pros                                                                                                                                                                                                                                                                                                       | Cons                                                                                                                                                                                                                                              |
| :------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Single index for both vectors    | <ul><li>You make requests to only a single index.</li><li>The linkage between dense and sparse vectors is implicit.</li><li>Simpler architecture with less operational overhead.</li></ul>                                                                                                                 | <ul><li>You can't do sparse-only queries.</li><li>You can't use integrated embedding and reranking.</li></ul>                                                                                                                                     |
| Separate indexes per vector type | <ul><li>You can start with dense vectors for semantic search and add sparse vectors for lexical search later.</li><li>You can do sparse-only queries.</li><li>You can rerank at multiple levels (for each index and for merged results).</li><li>You can use integrated embedding and reranking.</li></ul> | <ul><li>You need to manage and make requests to two separate indexes.</li><li>You need to maintain the linkage between sparse and dense vectors across indexes.</li><li>More complex architecture with additional operational overhead.</li></ul> |

## Choosing the right approach

**For most use cases, a single index that stores both dense and sparse vectors is recommended.**

* This approach provides a simpler architecture with less operational overhead. You make requests to a single index rather than managing and querying two separate indexes.
* The linkage between dense and sparse vectors is implicit, eliminating the need to maintain explicit linkages across indexes.
* You can perform hybrid queries with a single request, reducing latency and complexity compared to querying separate indexes and merging results.

**Consider using separate indexes only when:**

* You need to do sparse-only queries.
* You want to use Pinecone's integrated sparse model ([`pinecone-sparse-english-v0`](/models/pinecone-sparse-english-v0)), which only works with indexes that store sparse vectors.
* You need complete independence in reranking results from each index.
* You require the flexibility to manage dense and sparse vectors in separate indexes.

## Normalize sparse and dense values

A single index that stores both vector types doesn't reconcile their score ranges. The two scoring components have very different shapes:

* **Dense vectors** scored with `dotproduct` against unit-norm embeddings produce values roughly in `[-1, 1]` (or close, depending on the embedding model).
* **BM25-style sparse weights** and `pinecone-sparse-english-v0` outputs are **unbounded positive** values that scale with term frequency, document length, and vocabulary distribution. Raw scores can run into double digits.

Without explicit weighting, the sparse component dominates the combined score. To make the two signals comparable, apply a **convex combination** at query time using an `alpha` parameter:

* `combined = alpha * dense + (1 - alpha) * sparse`
* `alpha = 1.0` ranks by dense only (pure semantic).
* `alpha = 0.0` ranks by sparse only (pure lexical).
* `alpha = 0.5` weights the two signals equally.

Pinecone applies this weighting by **scaling the query vectors before sending them to the index** (the index itself stores raw values). Use the [`hybrid_score_norm`](#search-the-index-with-explicit-weighting) helper documented in the walkthrough below; it multiplies the dense values by `alpha` and the sparse values by `1 - alpha`, so the underlying dotproduct produces the desired combination.

### Choosing alpha

There's no universal best value — alpha depends on your data and query distribution. Reasonable starting points:

* **`alpha = 0.75`** (dense-leaning) — good default for natural-language queries on conversational or document-style content.
* **`alpha = 0.5`** — balanced; useful when keyword and semantic signals contribute equally (e.g., mixed exact-match and synonym queries).
* **`alpha = 0.25`** (sparse-leaning) — good for queries with high keyword specificity (product SKUs, technical IDs, named entities).

We recommend evaluating multiple alpha values against a labeled relevance set drawn from your own workload.

<Note>
  If your workload is text-centric, an [index with a document schema](/guides/get-started/concepts#document) sidesteps the alpha-tuning step entirely: declare BM25 and vector fields in one schema and pick a ranking signal per query, with no normalization to fit. See [Full-text search](/guides/search/full-text-search).
</Note>

## Use a single index for dense and sparse vectors

To perform hybrid search with a single index that stores both dense and sparse vectors, follow these steps:

<Steps>
  <Step title="Create the index">
    <a />

    To store both dense and sparse vectors in a single index, use the [`create_index`](/reference/api/latest/control-plane/create_index) operation, setting the `vector_type` to `dense` and the `metric` to `dotproduct`. This is the only combination that supports dense/sparse search on a single index.

    ```python Python theme={null}
    from pinecone.grpc import PineconeGRPC as Pinecone
    from pinecone import ServerlessSpec

    pc = Pinecone(api_key="YOUR_API_KEY")

    index_name = "hybrid-index"

    if not pc.has_index(index_name):
        pc.create_index(
            name=index_name,
            vector_type="dense",
            dimension=1024,
            metric="dotproduct",
            spec=ServerlessSpec(
                cloud="aws",
                region="us-east-1"
            )
        )
    ```
  </Step>

  <Step title="Generate vectors">
    <a />

    Use Pinecone's [hosted embedding models](/guides/index-data/create-an-index#embedding-models) to [convert data into dense and sparse vectors](/reference/api/latest/inference/generate-embeddings).

    ```python Python [expandable] theme={null}
    # Define the records
    data = [
        { "_id": "vec1", "chunk_text": "Apple Inc. issued a $10 billion corporate bond in 2023." },
        { "_id": "vec2", "chunk_text": "ETFs tracking the S&P 500 outperformed active funds last year." },
        { "_id": "vec3", "chunk_text": "Tesla's options volume surged after the latest earnings report." },
        { "_id": "vec4", "chunk_text": "Dividend aristocrats are known for consistently raising payouts." },
        { "_id": "vec5", "chunk_text": "The Federal Reserve raised interest rates by 0.25% to curb inflation." },
        { "_id": "vec6", "chunk_text": "Unemployment hit a record low of 3.7% in Q4 of 2024." },
        { "_id": "vec7", "chunk_text": "The CPI index rose by 6% in July 2024, raising concerns about purchasing power." },
        { "_id": "vec8", "chunk_text": "GDP growth in emerging markets outpaced developed economies." },
        { "_id": "vec9", "chunk_text": "Amazon's acquisition of MGM Studios was valued at $8.45 billion." },
        { "_id": "vec10", "chunk_text": "Alphabet reported a 20% increase in advertising revenue." },
        { "_id": "vec11", "chunk_text": "ExxonMobil announced a special dividend after record profits." },
        { "_id": "vec12", "chunk_text": "Tesla plans a 3-for-1 stock split to attract retail investors." },
        { "_id": "vec13", "chunk_text": "Credit card APRs reached an all-time high of 22.8% in 2024." },
        { "_id": "vec14", "chunk_text": "A 529 college savings plan offers tax advantages for education." },
        { "_id": "vec15", "chunk_text": "Emergency savings should ideally cover 6 months of expenses." },
        { "_id": "vec16", "chunk_text": "The average mortgage rate rose to 7.1% in December." },
        { "_id": "vec17", "chunk_text": "The SEC fined a hedge fund $50 million for insider trading." },
        { "_id": "vec18", "chunk_text": "New ESG regulations require companies to disclose climate risks." },
        { "_id": "vec19", "chunk_text": "The IRS introduced a new tax bracket for high earners." },
        { "_id": "vec20", "chunk_text": "Compliance with GDPR is mandatory for companies operating in Europe." },
        { "_id": "vec21", "chunk_text": "What are the best-performing green bonds in a rising rate environment?" },
        { "_id": "vec22", "chunk_text": "How does inflation impact the real yield of Treasury bonds?" },
        { "_id": "vec23", "chunk_text": "Top SPAC mergers in the technology sector for 2024." },
        { "_id": "vec24", "chunk_text": "Are stablecoins a viable hedge against currency devaluation?" },
        { "_id": "vec25", "chunk_text": "Comparison of Roth IRA vs 401(k) for high-income earners." },
        { "_id": "vec26", "chunk_text": "Stock splits and their effect on investor sentiment." },
        { "_id": "vec27", "chunk_text": "Tech IPOs that disappointed in their first year." },
        { "_id": "vec28", "chunk_text": "Impact of interest rate hikes on bank stocks." },
        { "_id": "vec29", "chunk_text": "Growth vs. value investing strategies in 2024." },
        { "_id": "vec30", "chunk_text": "The role of artificial intelligence in quantitative trading." },
        { "_id": "vec31", "chunk_text": "What are the implications of quantitative tightening on equities?" },
        { "_id": "vec32", "chunk_text": "How does compounding interest affect long-term investments?" },
        { "_id": "vec33", "chunk_text": "What are the best assets to hedge against inflation?" },
        { "_id": "vec34", "chunk_text": "Can ETFs provide better diversification than mutual funds?" },
        { "_id": "vec35", "chunk_text": "Unemployment hit at 2.4% in Q3 of 2024." },
        { "_id": "vec36", "chunk_text": "Unemployment is expected to hit 2.5% in Q3 of 2024." },
        { "_id": "vec37", "chunk_text": "In Q3 2025 unemployment for the prior year was revised to 2.2%"},
        { "_id": "vec38", "chunk_text": "Emerging markets witnessed increased foreign direct investment as global interest rates stabilized." },
        { "_id": "vec39", "chunk_text": "The rise in energy prices significantly impacted inflation trends during the first half of 2024." },
        { "_id": "vec40", "chunk_text": "Labor market trends show a declining participation rate despite record low unemployment in 2024." },
        { "_id": "vec41", "chunk_text": "Forecasts of global supply chain disruptions eased in late 2024, but consumer prices remained elevated due to persistent demand." },
        { "_id": "vec42", "chunk_text": "Tech sector layoffs in Q3 2024 have reshaped hiring trends across high-growth industries." },
        { "_id": "vec43", "chunk_text": "The U.S. dollar weakened against a basket of currencies as the global economy adjusted to shifting trade balances." },
        { "_id": "vec44", "chunk_text": "Central banks worldwide increased gold reserves to hedge against geopolitical and economic instability." },
        { "_id": "vec45", "chunk_text": "Corporate earnings in Q4 2024 were largely impacted by rising raw material costs and currency fluctuations." },
        { "_id": "vec46", "chunk_text": "Economic recovery in Q2 2024 relied heavily on government spending in infrastructure and green energy projects." },
        { "_id": "vec47", "chunk_text": "The housing market saw a rebound in late 2024, driven by falling mortgage rates and pent-up demand." },
        { "_id": "vec48", "chunk_text": "Wage growth outpaced inflation for the first time in years, signaling improved purchasing power in 2024." },
        { "_id": "vec49", "chunk_text": "China's economic growth in 2024 slowed to its lowest level in decades due to structural reforms and weak exports." },
        { "_id": "vec50", "chunk_text": "AI-driven automation in the manufacturing sector boosted productivity but raised concerns about job displacement." },
        { "_id": "vec51", "chunk_text": "The European Union introduced new fiscal policies in 2024 aimed at reducing public debt without stifling growth." },
        { "_id": "vec52", "chunk_text": "Record-breaking weather events in early 2024 have highlighted the growing economic impact of climate change." },
        { "_id": "vec53", "chunk_text": "Cryptocurrencies faced regulatory scrutiny in 2024, leading to volatility and reduced market capitalization." },
        { "_id": "vec54", "chunk_text": "The global tourism sector showed signs of recovery in late 2024 after years of pandemic-related setbacks." },
        { "_id": "vec55", "chunk_text": "Trade tensions between the U.S. and China escalated in 2024, impacting global supply chains and investment flows." },
        { "_id": "vec56", "chunk_text": "Consumer confidence indices remained resilient in Q2 2024 despite fears of an impending recession." },
        { "_id": "vec57", "chunk_text": "Startups in 2024 faced tighter funding conditions as venture capitalists focused on profitability over growth." },
        { "_id": "vec58", "chunk_text": "Oil production cuts in Q1 2024 by OPEC nations drove prices higher, influencing global energy policies." },
        { "_id": "vec59", "chunk_text": "The adoption of digital currencies by central banks increased in 2024, reshaping monetary policy frameworks." },
        { "_id": "vec60", "chunk_text": "Healthcare spending in 2024 surged as governments expanded access to preventive care and pandemic preparedness." },
        { "_id": "vec61", "chunk_text": "The World Bank reported declining poverty rates globally, but regional disparities persisted." },
        { "_id": "vec62", "chunk_text": "Private equity activity in 2024 focused on renewable energy and technology sectors amid shifting investor priorities." },
        { "_id": "vec63", "chunk_text": "Population aging emerged as a critical economic issue in 2024, especially in advanced economies." },
        { "_id": "vec64", "chunk_text": "Rising commodity prices in 2024 strained emerging markets dependent on imports of raw materials." },
        { "_id": "vec65", "chunk_text": "The global shipping industry experienced declining freight rates in 2024 due to overcapacity and reduced demand." },
        { "_id": "vec66", "chunk_text": "Bank lending to small and medium-sized enterprises surged in 2024 as governments incentivized entrepreneurship." },
        { "_id": "vec67", "chunk_text": "Renewable energy projects accounted for a record share of global infrastructure investment in 2024." },
        { "_id": "vec68", "chunk_text": "Cybersecurity spending reached new highs in 2024, reflecting the growing threat of digital attacks on infrastructure." },
        { "_id": "vec69", "chunk_text": "The agricultural sector faced challenges in 2024 due to extreme weather and rising input costs." },
        { "_id": "vec70", "chunk_text": "Consumer spending patterns shifted in 2024, with a greater focus on experiences over goods." },
        { "_id": "vec71", "chunk_text": "The economic impact of the 2008 financial crisis was mitigated by quantitative easing policies." },
        { "_id": "vec72", "chunk_text": "In early 2024, global GDP growth slowed, driven by weaker exports in Asia and Europe." },
        { "_id": "vec73", "chunk_text": "The historical relationship between inflation and unemployment is explained by the Phillips Curve." },
        { "_id": "vec74", "chunk_text": "The World Trade Organization's role in resolving disputes was tested in 2024." },
        { "_id": "vec75", "chunk_text": "The collapse of Silicon Valley Bank raised questions about regulatory oversight in 2024." },
        { "_id": "vec76", "chunk_text": "The cost of living crisis has been exacerbated by stagnant wage growth and rising inflation." },
        { "_id": "vec77", "chunk_text": "Supply chain resilience became a top priority for multinational corporations in 2024." },
        { "_id": "vec78", "chunk_text": "Consumer sentiment surveys in 2024 reflected optimism despite high interest rates." },
        { "_id": "vec79", "chunk_text": "The resurgence of industrial policy in Q1 2024 focused on decoupling critical supply chains." },
        { "_id": "vec80", "chunk_text": "Technological innovation in the fintech sector disrupted traditional banking in 2024." },
        { "_id": "vec81", "chunk_text": "The link between climate change and migration patterns is increasingly recognized." },
        { "_id": "vec82", "chunk_text": "Renewable energy subsidies in 2024 reduced the global reliance on fossil fuels." },
        { "_id": "vec83", "chunk_text": "The economic fallout of geopolitical tensions was evident in rising defense budgets worldwide." },
        { "_id": "vec84", "chunk_text": "The IMF's 2024 global outlook highlighted risks of stagflation in emerging markets." },
        { "_id": "vec85", "chunk_text": "Declining birth rates in advanced economies pose long-term challenges for labor markets." },
        { "_id": "vec86", "chunk_text": "Digital transformation initiatives in 2024 drove productivity gains in the services sector." },
        { "_id": "vec87", "chunk_text": "The U.S. labor market's resilience in 2024 defied predictions of a severe recession." },
        { "_id": "vec88", "chunk_text": "New fiscal measures in the European Union aimed to stabilize debt levels post-pandemic." },
        { "_id": "vec89", "chunk_text": "Venture capital investments in 2024 leaned heavily toward AI and automation startups." },
        { "_id": "vec90", "chunk_text": "The surge in e-commerce in 2024 was facilitated by advancements in logistics technology." },
        { "_id": "vec91", "chunk_text": "The impact of ESG investing on corporate strategies has been a major focus in 2024." },
        { "_id": "vec92", "chunk_text": "Income inequality widened in 2024 despite strong economic growth in developed nations." },
        { "_id": "vec93", "chunk_text": "The collapse of FTX highlighted the volatility and risks associated with cryptocurrencies." },
        { "_id": "vec94", "chunk_text": "Cyberattacks targeting financial institutions in 2024 led to record cybersecurity spending." },
        { "_id": "vec95", "chunk_text": "Automation in agriculture in 2024 increased yields but displaced rural workers." },
        { "_id": "vec96", "chunk_text": "New trade agreements signed 2022 will make an impact in 2024"},
    ]
    ```

    ```python Python theme={null}
    # Convert the chunk_text into dense vectors
    dense_embeddings = pc.inference.embed(
        model="llama-text-embed-v2",
        inputs=[d['chunk_text'] for d in data],
        parameters={"input_type": "passage", "truncate": "END"}
    )

    # Convert the chunk_text into sparse vectors
    sparse_embeddings = pc.inference.embed(
        model="pinecone-sparse-english-v0",
        inputs=[d['chunk_text'] for d in data],
        parameters={"input_type": "passage", "truncate": "END"}
    )
    ```
  </Step>

  <Step title="Upsert records with dense and sparse vectors">
    <a />

    Use the [`upsert`](/reference/api/latest/data-plane/upsert) operation, specifying dense values in the `value` parameter and sparse values in the `sparse_values` parameter.

    <Note>
      Only indexes that store dense vectors with the [dotproduct distance metric](/guides/index-data/indexing-overview#dotproduct) accept records that also have sparse vectors. Upserting such records into an index with a different distance metric will succeed, but querying will return an error.
    </Note>

    ```Python Python theme={null}
    # Target the index
    # To get the unique host for an index, 
    # see https://docs.pinecone.io/guides/manage-data/target-an-index
    index = pc.Index(host="INDEX_HOST")

    # Each record contains an ID, a dense vector, a sparse vector, and the original text as metadata
    records = []
    for d, de, se in zip(data, dense_embeddings, sparse_embeddings):
        records.append({
            "id": d['_id'],
            "values": de['values'],
            "sparse_values": {'indices': se['sparse_indices'], 'values': se['sparse_values']},
            "metadata": {'text': d['chunk_text']}
        })

    # Upsert the records into the index
    index.upsert(
        vectors=records,
        namespace="example-namespace"
    )
    ```
  </Step>

  <Step title="Search the index">
    <a />

    Use the [`embed`](/reference/api/latest/inference/generate-embeddings) operation to convert your query into a dense vector and a sparse vector, and then use the [`query`](/reference/api/latest/data-plane/query) operation to search the index for the 40 most relevant records.

    ```Python Python theme={null}
    query = "Q3 2024 us economic data"

    # Convert the query into a dense vector
    dense_query_embedding = pc.inference.embed(
        model="llama-text-embed-v2",
        inputs=query,
        parameters={"input_type": "query", "truncate": "END"}
    )

    # Convert the query into a sparse vector
    sparse_query_embedding = pc.inference.embed(
        model="pinecone-sparse-english-v0",
        inputs=query,
        parameters={"input_type": "query", "truncate": "END"}
    )

    for d, s in zip(dense_query_embedding, sparse_query_embedding):
        query_response = index.query(
            namespace="example-namespace",
            top_k=40,
            vector=d['values'],
            sparse_vector={'indices': s['sparse_indices'], 'values': s['sparse_values']},
            include_values=False,
            include_metadata=True
        )
        print(query_response)
    ```

    ```python Response [expandable] theme={null}
    {'matches': [{'id': 'vec35',
                  'metadata': {'text': 'Unemployment hit at 2.4% in Q3 of 2024.'},
                  'score': 7.92519569,
                  'values': []},
                 {'id': 'vec46',
                  'metadata': {'text': 'Economic recovery in Q2 2024 relied '
                                       'heavily on government spending in '
                                       'infrastructure and green energy projects.'},
                  'score': 7.86733627,
                  'values': []},
                 {'id': 'vec36',
                  'metadata': {'text': 'Unemployment is expected to hit 2.5% in Q3 '
                                       'of 2024.'},
                  'score': 7.82636,
                  'values': []},
                 {'id': 'vec42',
                  'metadata': {'text': 'Tech sector layoffs in Q3 2024 have '
                                       'reshaped hiring trends across high-growth '
                                       'industries.'},
                  'score': 7.79465914,
                  'values': []},
                 {'id': 'vec49',
                  'metadata': {'text': "China's economic growth in 2024 slowed to "
                                       'its lowest level in decades due to '
                                       'structural reforms and weak exports.'},
                  'score': 7.46323156,
                  'values': []},
                 {'id': 'vec63',
                  'metadata': {'text': 'Population aging emerged as a critical '
                                       'economic issue in 2024, especially in '
                                       'advanced economies.'},
                  'score': 7.29055929,
                  'values': []},
                 {'id': 'vec92',
                  'metadata': {'text': 'Income inequality widened in 2024 despite '
                                       'strong economic growth in developed '
                                       'nations.'},
                  'score': 6.51210213,
                  'values': []},
                 {'id': 'vec52',
                  'metadata': {'text': 'Record-breaking weather events in early '
                                       '2024 have highlighted the growing economic '
                                       'impact of climate change.'},
                  'score': 6.4125514,
                  'values': []},
                 {'id': 'vec62',
                  'metadata': {'text': 'Private equity activity in 2024 focused on '
                                       'renewable energy and technology sectors '
                                       'amid shifting investor priorities.'},
                  'score': 4.8084693,
                  'values': []},
                 {'id': 'vec89',
                  'metadata': {'text': 'Venture capital investments in 2024 leaned '
                                       'heavily toward AI and automation '
                                       'startups.'},
                  'score': 4.7974205,
                  'values': []},
                 {'id': 'vec57',
                  'metadata': {'text': 'Startups in 2024 faced tighter funding '
                                       'conditions as venture capitalists focused '
                                       'on profitability over growth.'},
                  'score': 4.72518444,
                  'values': []},
                 {'id': 'vec37',
                  'metadata': {'text': 'In Q3 2025 unemployment for the prior year '
                                       'was revised to 2.2%'},
                  'score': 4.71824408,
                  'values': []},
                 {'id': 'vec69',
                  'metadata': {'text': 'The agricultural sector faced challenges '
                                       'in 2024 due to extreme weather and rising '
                                       'input costs.'},
                  'score': 4.66726208,
                  'values': []},
                 {'id': 'vec60',
                  'metadata': {'text': 'Healthcare spending in 2024 surged as '
                                       'governments expanded access to preventive '
                                       'care and pandemic preparedness.'},
                  'score': 4.62045908,
                  'values': []},
                 {'id': 'vec55',
                  'metadata': {'text': 'Trade tensions between the U.S. and China '
                                       'escalated in 2024, impacting global supply '
                                       'chains and investment flows.'},
                  'score': 4.59764862,
                  'values': []},
                 {'id': 'vec51',
                  'metadata': {'text': 'The European Union introduced new fiscal '
                                       'policies in 2024 aimed at reducing public '
                                       'debt without stifling growth.'},
                  'score': 4.57397079,
                  'values': []},
                 {'id': 'vec70',
                  'metadata': {'text': 'Consumer spending patterns shifted in '
                                       '2024, with a greater focus on experiences '
                                       'over goods.'},
                  'score': 4.55043507,
                  'values': []},
                 {'id': 'vec87',
                  'metadata': {'text': "The U.S. labor market's resilience in 2024 "
                                       'defied predictions of a severe recession.'},
                  'score': 4.51785707,
                  'values': []},
                 {'id': 'vec90',
                  'metadata': {'text': 'The surge in e-commerce in 2024 was '
                                       'facilitated by advancements in logistics '
                                       'technology.'},
                  'score': 4.47754288,
                  'values': []},
                 {'id': 'vec78',
                  'metadata': {'text': 'Consumer sentiment surveys in 2024 '
                                       'reflected optimism despite high interest '
                                       'rates.'},
                  'score': 4.46246624,
                  'values': []},
                 {'id': 'vec53',
                  'metadata': {'text': 'Cryptocurrencies faced regulatory scrutiny '
                                       'in 2024, leading to volatility and reduced '
                                       'market capitalization.'},
                  'score': 4.4435873,
                  'values': []},
                 {'id': 'vec45',
                  'metadata': {'text': 'Corporate earnings in Q4 2024 were largely '
                                       'impacted by rising raw material costs and '
                                       'currency fluctuations.'},
                  'score': 4.43836403,
                  'values': []},
                 {'id': 'vec82',
                  'metadata': {'text': 'Renewable energy subsidies in 2024 reduced '
                                       'the global reliance on fossil fuels.'},
                  'score': 4.43601322,
                  'values': []},
                 {'id': 'vec94',
                  'metadata': {'text': 'Cyberattacks targeting financial '
                                       'institutions in 2024 led to record '
                                       'cybersecurity spending.'},
                  'score': 4.41334057,
                  'values': []},
                 {'id': 'vec47',
                  'metadata': {'text': 'The housing market saw a rebound in late '
                                       '2024, driven by falling mortgage rates and '
                                       'pent-up demand.'},
                  'score': 4.39900732,
                  'values': []},
                 {'id': 'vec41',
                  'metadata': {'text': 'Forecasts of global supply chain '
                                       'disruptions eased in late 2024, but '
                                       'consumer prices remained elevated due to '
                                       'persistent demand.'},
                  'score': 4.37389421,
                  'values': []},
                 {'id': 'vec84',
                  'metadata': {'text': "The IMF's 2024 global outlook highlighted "
                                       'risks of stagflation in emerging markets.'},
                  'score': 4.37335157,
                  'values': []},
                 {'id': 'vec96',
                  'metadata': {'text': 'New trade agreements signed 2022 will make '
                                       'an impact in 2024'},
                  'score': 4.33860636,
                  'values': []},
                 {'id': 'vec79',
                  'metadata': {'text': 'The resurgence of industrial policy in Q1 '
                                       '2024 focused on decoupling critical supply '
                                       'chains.'},
                  'score': 4.33784199,
                  'values': []},
                 {'id': 'vec6',
                  'metadata': {'text': 'Unemployment hit a record low of 3.7% in '
                                       'Q4 of 2024.'},
                  'score': 4.33008051,
                  'values': []},
                 {'id': 'vec65',
                  'metadata': {'text': 'The global shipping industry experienced '
                                       'declining freight rates in 2024 due to '
                                       'overcapacity and reduced demand.'},
                  'score': 4.3228569,
                  'values': []},
                 {'id': 'vec64',
                  'metadata': {'text': 'Rising commodity prices in 2024 strained '
                                       'emerging markets dependent on imports of '
                                       'raw materials.'},
                  'score': 4.32269621,
                  'values': []},
                 {'id': 'vec95',
                  'metadata': {'text': 'Automation in agriculture in 2024 '
                                       'increased yields but displaced rural '
                                       'workers.'},
                  'score': 4.31127262,
                  'values': []},
                 {'id': 'vec86',
                  'metadata': {'text': 'Digital transformation initiatives in 2024 '
                                       'drove productivity gains in the services '
                                       'sector.'},
                  'score': 4.30181122,
                  'values': []},
                 {'id': 'vec66',
                  'metadata': {'text': 'Bank lending to small and medium-sized '
                                       'enterprises surged in 2024 as governments '
                                       'incentivized entrepreneurship.'},
                  'score': 4.27241945,
                  'values': []},
                 {'id': 'vec58',
                  'metadata': {'text': 'Oil production cuts in Q1 2024 by OPEC '
                                       'nations drove prices higher, influencing '
                                       'global energy policies.'},
                  'score': 4.21715498,
                  'values': []},
                 {'id': 'vec80',
                  'metadata': {'text': 'Technological innovation in the fintech '
                                       'sector disrupted traditional banking in '
                                       '2024.'},
                  'score': 4.17712116,
                  'values': []},
                 {'id': 'vec75',
                  'metadata': {'text': 'The collapse of Silicon Valley Bank raised '
                                       'questions about regulatory oversight in '
                                       '2024.'},
                  'score': 4.16192341,
                  'values': []},
                 {'id': 'vec56',
                  'metadata': {'text': 'Consumer confidence indices remained '
                                       'resilient in Q2 2024 despite fears of an '
                                       'impending recession.'},
                  'score': 4.15782213,
                  'values': []},
                 {'id': 'vec67',
                  'metadata': {'text': 'Renewable energy projects accounted for a '
                                       'record share of global infrastructure '
                                       'investment in 2024.'},
                  'score': 4.14623,
                  'values': []}],
     'namespace': 'example-namespace',
     'usage': {'read_units': 9}}
    ```
  </Step>

  <Step title="Search the index with explicit weighting">
    <a />

    For a conceptual overview of why this normalization is needed, see [Normalize sparse and dense values](#normalize-sparse-and-dense-values).

    Because Pinecone views your sparse-dense vector as a single vector, it does not offer a built-in parameter to adjust the weight of a query's dense part against its sparse part; the index is agnostic to density or sparsity of coordinates in your vectors. You may, however, incorporate a linear weighting scheme by customizing your query vector, as demonstrated in the function below.

    The following example transforms vector values using an alpha parameter.

    ```Python Python theme={null}
    def hybrid_score_norm(dense, sparse, alpha: float):
        """Hybrid score using a convex combination

        alpha * dense + (1 - alpha) * sparse

        Args:
            dense: Array of floats representing
            sparse: a dict of `indices` and `values`
            alpha: scale between 0 and 1
        """
        if alpha < 0 or alpha > 1:
            raise ValueError("Alpha must be between 0 and 1")
        hs = {
            'indices': sparse['indices'],
            'values':  [v * (1 - alpha) for v in sparse['values']]
        }
        return [v * alpha for v in dense], hs
    ```

    The following example transforms a vector using the above function, then queries a Pinecone index.

    ```Python Python theme={null}
    sparse_vector = {
       'indices': [10, 45, 16],
       'values':  [0.5, 0.5, 0.2]
    }
    dense_vector = [0.1, 0.2, 0.3]

    hdense, hsparse = hybrid_score_norm(dense_vector, sparse_vector, alpha=0.75)

    query_response = index.query(
        namespace="example-namespace",
        top_k=10,
        vector=hdense,
        sparse_vector=hsparse
    )
    ```
  </Step>
</Steps>

## Use separate indexes for dense and sparse vectors

To perform hybrid search with separate indexes, follow these steps:

<Steps>
  <Step title="Create the indexes">
    <a />

    [Create one index for dense vectors](/guides/index-data/create-an-index#create-an-index-for-dense-vectors) and [another for sparse vectors](/guides/index-data/create-an-index#create-an-index-for-sparse-vectors), either with integrated embedding or for vectors created with external models.

    For example, the following code creates indexes with integrated embedding models.

    ```python Python theme={null}
    from pinecone import Pinecone

    pc = Pinecone(api_key="YOUR_API_KEY")

    dense_index_name = "dense-for-hybrid-py"
    sparse_index_name = "sparse-for-hybrid-py"

    if not pc.has_index(dense_index_name):
        pc.create_index_for_model(
            name=dense_index_name,
            cloud="aws",
            region="us-east-1",
            embed={
                "model":"llama-text-embed-v2",
                "field_map":{"text": "chunk_text"}
            }
        )

    if not pc.has_index(sparse_index_name):
        pc.create_index_for_model(
            name=sparse_index_name,
            cloud="aws",
            region="us-east-1",
            embed={
                "model":"pinecone-sparse-english-v0",
                "field_map":{"text": "chunk_text"}
            }
        )
    ```
  </Step>

  <Step title="Upsert dense and sparse vectors">
    <a />

    [Upsert dense vectors](/guides/index-data/upsert-data#upsert-dense-vectors) and [upsert sparse vectors](/guides/index-data/upsert-data#upsert-sparse-vectors) into their respective indexes.

    Make sure to establish a linkage between the dense and sparse vectors so you can merge and deduplicate search results later. For example, the following uses `_id` as the linkage, but you can use any other custom field as well. Because the indexes are integrated with embedding models, you provide the source texts and Pinecone converts them to vectors automatically.

    ```python Python [expandable] theme={null}
    # Define the records
    records = [
        { "_id": "vec1", "chunk_text": "Apple Inc. issued a $10 billion corporate bond in 2023." },
        { "_id": "vec2", "chunk_text": "ETFs tracking the S&P 500 outperformed active funds last year." },
        { "_id": "vec3", "chunk_text": "Tesla's options volume surged after the latest earnings report." },
        { "_id": "vec4", "chunk_text": "Dividend aristocrats are known for consistently raising payouts." },
        { "_id": "vec5", "chunk_text": "The Federal Reserve raised interest rates by 0.25% to curb inflation." },
        { "_id": "vec6", "chunk_text": "Unemployment hit a record low of 3.7% in Q4 of 2024." },
        { "_id": "vec7", "chunk_text": "The CPI index rose by 6% in July 2024, raising concerns about purchasing power." },
        { "_id": "vec8", "chunk_text": "GDP growth in emerging markets outpaced developed economies." },
        { "_id": "vec9", "chunk_text": "Amazon's acquisition of MGM Studios was valued at $8.45 billion." },
        { "_id": "vec10", "chunk_text": "Alphabet reported a 20% increase in advertising revenue." },
        { "_id": "vec11", "chunk_text": "ExxonMobil announced a special dividend after record profits." },
        { "_id": "vec12", "chunk_text": "Tesla plans a 3-for-1 stock split to attract retail investors." },
        { "_id": "vec13", "chunk_text": "Credit card APRs reached an all-time high of 22.8% in 2024." },
        { "_id": "vec14", "chunk_text": "A 529 college savings plan offers tax advantages for education." },
        { "_id": "vec15", "chunk_text": "Emergency savings should ideally cover 6 months of expenses." },
        { "_id": "vec16", "chunk_text": "The average mortgage rate rose to 7.1% in December." },
        { "_id": "vec17", "chunk_text": "The SEC fined a hedge fund $50 million for insider trading." },
        { "_id": "vec18", "chunk_text": "New ESG regulations require companies to disclose climate risks." },
        { "_id": "vec19", "chunk_text": "The IRS introduced a new tax bracket for high earners." },
        { "_id": "vec20", "chunk_text": "Compliance with GDPR is mandatory for companies operating in Europe." },
        { "_id": "vec21", "chunk_text": "What are the best-performing green bonds in a rising rate environment?" },
        { "_id": "vec22", "chunk_text": "How does inflation impact the real yield of Treasury bonds?" },
        { "_id": "vec23", "chunk_text": "Top SPAC mergers in the technology sector for 2024." },
        { "_id": "vec24", "chunk_text": "Are stablecoins a viable hedge against currency devaluation?" },
        { "_id": "vec25", "chunk_text": "Comparison of Roth IRA vs 401(k) for high-income earners." },
        { "_id": "vec26", "chunk_text": "Stock splits and their effect on investor sentiment." },
        { "_id": "vec27", "chunk_text": "Tech IPOs that disappointed in their first year." },
        { "_id": "vec28", "chunk_text": "Impact of interest rate hikes on bank stocks." },
        { "_id": "vec29", "chunk_text": "Growth vs. value investing strategies in 2024." },
        { "_id": "vec30", "chunk_text": "The role of artificial intelligence in quantitative trading." },
        { "_id": "vec31", "chunk_text": "What are the implications of quantitative tightening on equities?" },
        { "_id": "vec32", "chunk_text": "How does compounding interest affect long-term investments?" },
        { "_id": "vec33", "chunk_text": "What are the best assets to hedge against inflation?" },
        { "_id": "vec34", "chunk_text": "Can ETFs provide better diversification than mutual funds?" },
        { "_id": "vec35", "chunk_text": "Unemployment hit at 2.4% in Q3 of 2024." },
        { "_id": "vec36", "chunk_text": "Unemployment is expected to hit 2.5% in Q3 of 2024." },
        { "_id": "vec37", "chunk_text": "In Q3 2025 unemployment for the prior year was revised to 2.2%"},
        { "_id": "vec38", "chunk_text": "Emerging markets witnessed increased foreign direct investment as global interest rates stabilized." },
        { "_id": "vec39", "chunk_text": "The rise in energy prices significantly impacted inflation trends during the first half of 2024." },
        { "_id": "vec40", "chunk_text": "Labor market trends show a declining participation rate despite record low unemployment in 2024." },
        { "_id": "vec41", "chunk_text": "Forecasts of global supply chain disruptions eased in late 2024, but consumer prices remained elevated due to persistent demand." },
        { "_id": "vec42", "chunk_text": "Tech sector layoffs in Q3 2024 have reshaped hiring trends across high-growth industries." },
        { "_id": "vec43", "chunk_text": "The U.S. dollar weakened against a basket of currencies as the global economy adjusted to shifting trade balances." },
        { "_id": "vec44", "chunk_text": "Central banks worldwide increased gold reserves to hedge against geopolitical and economic instability." },
        { "_id": "vec45", "chunk_text": "Corporate earnings in Q4 2024 were largely impacted by rising raw material costs and currency fluctuations." },
        { "_id": "vec46", "chunk_text": "Economic recovery in Q2 2024 relied heavily on government spending in infrastructure and green energy projects." },
        { "_id": "vec47", "chunk_text": "The housing market saw a rebound in late 2024, driven by falling mortgage rates and pent-up demand." },
        { "_id": "vec48", "chunk_text": "Wage growth outpaced inflation for the first time in years, signaling improved purchasing power in 2024." },
        { "_id": "vec49", "chunk_text": "China's economic growth in 2024 slowed to its lowest level in decades due to structural reforms and weak exports." },
        { "_id": "vec50", "chunk_text": "AI-driven automation in the manufacturing sector boosted productivity but raised concerns about job displacement." },
        { "_id": "vec51", "chunk_text": "The European Union introduced new fiscal policies in 2024 aimed at reducing public debt without stifling growth." },
        { "_id": "vec52", "chunk_text": "Record-breaking weather events in early 2024 have highlighted the growing economic impact of climate change." },
        { "_id": "vec53", "chunk_text": "Cryptocurrencies faced regulatory scrutiny in 2024, leading to volatility and reduced market capitalization." },
        { "_id": "vec54", "chunk_text": "The global tourism sector showed signs of recovery in late 2024 after years of pandemic-related setbacks." },
        { "_id": "vec55", "chunk_text": "Trade tensions between the U.S. and China escalated in 2024, impacting global supply chains and investment flows." },
        { "_id": "vec56", "chunk_text": "Consumer confidence indices remained resilient in Q2 2024 despite fears of an impending recession." },
        { "_id": "vec57", "chunk_text": "Startups in 2024 faced tighter funding conditions as venture capitalists focused on profitability over growth." },
        { "_id": "vec58", "chunk_text": "Oil production cuts in Q1 2024 by OPEC nations drove prices higher, influencing global energy policies." },
        { "_id": "vec59", "chunk_text": "The adoption of digital currencies by central banks increased in 2024, reshaping monetary policy frameworks." },
        { "_id": "vec60", "chunk_text": "Healthcare spending in 2024 surged as governments expanded access to preventive care and pandemic preparedness." },
        { "_id": "vec61", "chunk_text": "The World Bank reported declining poverty rates globally, but regional disparities persisted." },
        { "_id": "vec62", "chunk_text": "Private equity activity in 2024 focused on renewable energy and technology sectors amid shifting investor priorities." },
        { "_id": "vec63", "chunk_text": "Population aging emerged as a critical economic issue in 2024, especially in advanced economies." },
        { "_id": "vec64", "chunk_text": "Rising commodity prices in 2024 strained emerging markets dependent on imports of raw materials." },
        { "_id": "vec65", "chunk_text": "The global shipping industry experienced declining freight rates in 2024 due to overcapacity and reduced demand." },
        { "_id": "vec66", "chunk_text": "Bank lending to small and medium-sized enterprises surged in 2024 as governments incentivized entrepreneurship." },
        { "_id": "vec67", "chunk_text": "Renewable energy projects accounted for a record share of global infrastructure investment in 2024." },
        { "_id": "vec68", "chunk_text": "Cybersecurity spending reached new highs in 2024, reflecting the growing threat of digital attacks on infrastructure." },
        { "_id": "vec69", "chunk_text": "The agricultural sector faced challenges in 2024 due to extreme weather and rising input costs." },
        { "_id": "vec70", "chunk_text": "Consumer spending patterns shifted in 2024, with a greater focus on experiences over goods." },
        { "_id": "vec71", "chunk_text": "The economic impact of the 2008 financial crisis was mitigated by quantitative easing policies." },
        { "_id": "vec72", "chunk_text": "In early 2024, global GDP growth slowed, driven by weaker exports in Asia and Europe." },
        { "_id": "vec73", "chunk_text": "The historical relationship between inflation and unemployment is explained by the Phillips Curve." },
        { "_id": "vec74", "chunk_text": "The World Trade Organization's role in resolving disputes was tested in 2024." },
        { "_id": "vec75", "chunk_text": "The collapse of Silicon Valley Bank raised questions about regulatory oversight in 2024." },
        { "_id": "vec76", "chunk_text": "The cost of living crisis has been exacerbated by stagnant wage growth and rising inflation." },
        { "_id": "vec77", "chunk_text": "Supply chain resilience became a top priority for multinational corporations in 2024." },
        { "_id": "vec78", "chunk_text": "Consumer sentiment surveys in 2024 reflected optimism despite high interest rates." },
        { "_id": "vec79", "chunk_text": "The resurgence of industrial policy in Q1 2024 focused on decoupling critical supply chains." },
        { "_id": "vec80", "chunk_text": "Technological innovation in the fintech sector disrupted traditional banking in 2024." },
        { "_id": "vec81", "chunk_text": "The link between climate change and migration patterns is increasingly recognized." },
        { "_id": "vec82", "chunk_text": "Renewable energy subsidies in 2024 reduced the global reliance on fossil fuels." },
        { "_id": "vec83", "chunk_text": "The economic fallout of geopolitical tensions was evident in rising defense budgets worldwide." },
        { "_id": "vec84", "chunk_text": "The IMF's 2024 global outlook highlighted risks of stagflation in emerging markets." },
        { "_id": "vec85", "chunk_text": "Declining birth rates in advanced economies pose long-term challenges for labor markets." },
        { "_id": "vec86", "chunk_text": "Digital transformation initiatives in 2024 drove productivity gains in the services sector." },
        { "_id": "vec87", "chunk_text": "The U.S. labor market's resilience in 2024 defied predictions of a severe recession." },
        { "_id": "vec88", "chunk_text": "New fiscal measures in the European Union aimed to stabilize debt levels post-pandemic." },
        { "_id": "vec89", "chunk_text": "Venture capital investments in 2024 leaned heavily toward AI and automation startups." },
        { "_id": "vec90", "chunk_text": "The surge in e-commerce in 2024 was facilitated by advancements in logistics technology." },
        { "_id": "vec91", "chunk_text": "The impact of ESG investing on corporate strategies has been a major focus in 2024." },
        { "_id": "vec92", "chunk_text": "Income inequality widened in 2024 despite strong economic growth in developed nations." },
        { "_id": "vec93", "chunk_text": "The collapse of FTX highlighted the volatility and risks associated with cryptocurrencies." },
        { "_id": "vec94", "chunk_text": "Cyberattacks targeting financial institutions in 2024 led to record cybersecurity spending." },
        { "_id": "vec95", "chunk_text": "Automation in agriculture in 2024 increased yields but displaced rural workers." },
        { "_id": "vec96", "chunk_text": "New trade agreements signed 2022 will make an impact in 2024"},
    ]
    ```

    ```python Python theme={null}
    # Target both indexes
    # To get the unique host for an index, 
    # see https://docs.pinecone.io/guides/manage-data/target-an-index
    dense_index = pc.Index(host="INDEX_HOST")
    sparse_index = pc.Index(host="INDEX_HOST")

    # Upsert the records
    # The `chunk_text` fields are converted to dense and sparse vectors
    dense_index.upsert_records("example-namespace", records)
    sparse_index.upsert_records("example-namespace", records)
    ```
  </Step>

  <Step title="Search by dense vectors">
    <a />

    Perform a [semantic search](/guides/search/semantic-search) against the index that stores dense vectors.

    For example, the following code searches that index for 40 records most semantically related to the query "Q3 2024 us economic data". Because the index is integrated with an embedding model, you provide the query as text and Pinecone converts the text to a dense vector automatically.

    ```python Python theme={null}
    query = "Q3 2024 us economic data"

    dense_results = dense_index.search(
        namespace="example-namespace",
        query={
            "top_k": 40,
            "inputs": {
                "text": query
            }
        }
    )

    print(dense_results)
    ```

    ```python Response [expandable] theme={null}
    {'result': {'hits': [{'_id': 'vec35',
                          '_score': 0.8629686832427979,
                          'fields': {'chunk_text': 'Unemployment hit at 2.4% in Q3 '
                                                   'of 2024.'}},
                         {'_id': 'vec36',
                          '_score': 0.8573639988899231,
                          'fields': {'chunk_text': 'Unemployment is expected to '
                                                   'hit 2.5% in Q3 of 2024.'}},
                         {'_id': 'vec6',
                          '_score': 0.8535352945327759,
                          'fields': {'chunk_text': 'Unemployment hit a record low '
                                                   'of 3.7% in Q4 of 2024.'}},
                         {'_id': 'vec42',
                          '_score': 0.8336166739463806,
                          'fields': {'chunk_text': 'Tech sector layoffs in Q3 2024 '
                                                   'have reshaped hiring trends '
                                                   'across high-growth '
                                                   'industries.'}},
                         {'_id': 'vec48',
                          '_score': 0.8328524827957153,
                          'fields': {'chunk_text': 'Wage growth outpaced inflation '
                                                   'for the first time in years, '
                                                   'signaling improved purchasing '
                                                   'power in 2024.'}},
                         {'_id': 'vec55',
                          '_score': 0.8322604298591614,
                          'fields': {'chunk_text': 'Trade tensions between the '
                                                   'U.S. and China escalated in '
                                                   '2024, impacting global supply '
                                                   'chains and investment flows.'}},
                         {'_id': 'vec45',
                          '_score': 0.8309446573257446,
                          'fields': {'chunk_text': 'Corporate earnings in Q4 2024 '
                                                   'were largely impacted by '
                                                   'rising raw material costs and '
                                                   'currency fluctuations.'}},
                         {'_id': 'vec72',
                          '_score': 0.8275909423828125,
                          'fields': {'chunk_text': 'In early 2024, global GDP '
                                                   'growth slowed, driven by '
                                                   'weaker exports in Asia and '
                                                   'Europe.'}},
                         {'_id': 'vec29',
                          '_score': 0.8270887136459351,
                          'fields': {'chunk_text': 'Growth vs. value investing '
                                                   'strategies in 2024.'}},
                         {'_id': 'vec46',
                          '_score': 0.8263787627220154,
                          'fields': {'chunk_text': 'Economic recovery in Q2 2024 '
                                                   'relied heavily on government '
                                                   'spending in infrastructure and '
                                                   'green energy projects.'}},
                         {'_id': 'vec79',
                          '_score': 0.8258304595947266,
                          'fields': {'chunk_text': 'The resurgence of industrial '
                                                   'policy in Q1 2024 focused on '
                                                   'decoupling critical supply '
                                                   'chains.'}},
                         {'_id': 'vec87',
                          '_score': 0.8257324695587158,
                          'fields': {'chunk_text': "The U.S. labor market's "
                                                   'resilience in 2024 defied '
                                                   'predictions of a severe '
                                                   'recession.'}},
                         {'_id': 'vec40',
                          '_score': 0.8253997564315796,
                          'fields': {'chunk_text': 'Labor market trends show a '
                                                   'declining participation rate '
                                                   'despite record low '
                                                   'unemployment in 2024.'}},
                         {'_id': 'vec37',
                          '_score': 0.8235862255096436,
                          'fields': {'chunk_text': 'In Q3 2025 unemployment for '
                                                   'the prior year was revised to '
                                                   '2.2%'}},
                         {'_id': 'vec58',
                          '_score': 0.8233317136764526,
                          'fields': {'chunk_text': 'Oil production cuts in Q1 2024 '
                                                   'by OPEC nations drove prices '
                                                   'higher, influencing global '
                                                   'energy policies.'}},
                         {'_id': 'vec47',
                          '_score': 0.8231339454650879,
                          'fields': {'chunk_text': 'The housing market saw a '
                                                   'rebound in late 2024, driven '
                                                   'by falling mortgage rates and '
                                                   'pent-up demand.'}},
                         {'_id': 'vec41',
                          '_score': 0.8187897801399231,
                          'fields': {'chunk_text': 'Forecasts of global supply '
                                                   'chain disruptions eased in '
                                                   'late 2024, but consumer prices '
                                                   'remained elevated due to '
                                                   'persistent demand.'}},
                         {'_id': 'vec56',
                          '_score': 0.8155254125595093,
                          'fields': {'chunk_text': 'Consumer confidence indices '
                                                   'remained resilient in Q2 2024 '
                                                   'despite fears of an impending '
                                                   'recession.'}},
                         {'_id': 'vec63',
                          '_score': 0.8136948347091675,
                          'fields': {'chunk_text': 'Population aging emerged as a '
                                                   'critical economic issue in '
                                                   '2024, especially in advanced '
                                                   'economies.'}},
                         {'_id': 'vec52',
                          '_score': 0.8129132390022278,
                          'fields': {'chunk_text': 'Record-breaking weather events '
                                                   'in early 2024 have highlighted '
                                                   'the growing economic impact of '
                                                   'climate change.'}},
                         {'_id': 'vec23',
                          '_score': 0.8126378655433655,
                          'fields': {'chunk_text': 'Top SPAC mergers in the '
                                                   'technology sector for 2024.'}},
                         {'_id': 'vec62',
                          '_score': 0.8116977214813232,
                          'fields': {'chunk_text': 'Private equity activity in '
                                                   '2024 focused on renewable '
                                                   'energy and technology sectors '
                                                   'amid shifting investor '
                                                   'priorities.'}},
                         {'_id': 'vec64',
                          '_score': 0.8109902739524841,
                          'fields': {'chunk_text': 'Rising commodity prices in '
                                                   '2024 strained emerging markets '
                                                   'dependent on imports of raw '
                                                   'materials.'}},
                         {'_id': 'vec54',
                          '_score': 0.8092231154441833,
                          'fields': {'chunk_text': 'The global tourism sector '
                                                   'showed signs of recovery in '
                                                   'late 2024 after years of '
                                                   'pandemic-related setbacks.'}},
                         {'_id': 'vec96',
                          '_score': 0.8075559735298157,
                          'fields': {'chunk_text': 'New trade agreements signed '
                                                   '2022 will make an impact in '
                                                   '2024'}},
                         {'_id': 'vec49',
                          '_score': 0.8062589764595032,
                          'fields': {'chunk_text': "China's economic growth in "
                                                   '2024 slowed to its lowest '
                                                   'level in decades due to '
                                                   'structural reforms and weak '
                                                   'exports.'}},
                         {'_id': 'vec7',
                          '_score': 0.8034461140632629,
                          'fields': {'chunk_text': 'The CPI index rose by 6% in '
                                                   'July 2024, raising concerns '
                                                   'about purchasing power.'}},
                         {'_id': 'vec84',
                          '_score': 0.8027160167694092,
                          'fields': {'chunk_text': "The IMF's 2024 global outlook "
                                                   'highlighted risks of '
                                                   'stagflation in emerging '
                                                   'markets.'}},
                         {'_id': 'vec13',
                          '_score': 0.8010239601135254,
                          'fields': {'chunk_text': 'Credit card APRs reached an '
                                                   'all-time high of 22.8% in '
                                                   '2024.'}},
                         {'_id': 'vec53',
                          '_score': 0.8007135391235352,
                          'fields': {'chunk_text': 'Cryptocurrencies faced '
                                                   'regulatory scrutiny in 2024, '
                                                   'leading to volatility and '
                                                   'reduced market '
                                                   'capitalization.'}},
                         {'_id': 'vec60',
                          '_score': 0.7980866432189941,
                          'fields': {'chunk_text': 'Healthcare spending in 2024 '
                                                   'surged as governments expanded '
                                                   'access to preventive care and '
                                                   'pandemic preparedness.'}},
                         {'_id': 'vec91',
                          '_score': 0.7980680465698242,
                          'fields': {'chunk_text': 'The impact of ESG investing on '
                                                   'corporate strategies has been '
                                                   'a major focus in 2024.'}},
                         {'_id': 'vec68',
                          '_score': 0.797269880771637,
                          'fields': {'chunk_text': 'Cybersecurity spending reached '
                                                   'new highs in 2024, reflecting '
                                                   'the growing threat of digital '
                                                   'attacks on infrastructure.'}},
                         {'_id': 'vec59',
                          '_score': 0.795337438583374,
                          'fields': {'chunk_text': 'The adoption of digital '
                                                   'currencies by central banks '
                                                   'increased in 2024, reshaping '
                                                   'monetary policy frameworks.'}},
                         {'_id': 'vec39',
                          '_score': 0.793889045715332,
                          'fields': {'chunk_text': 'The rise in energy prices '
                                                   'significantly impacted '
                                                   'inflation trends during the '
                                                   'first half of 2024.'}},
                         {'_id': 'vec66',
                          '_score': 0.7919396162033081,
                          'fields': {'chunk_text': 'Bank lending to small and '
                                                   'medium-sized enterprises '
                                                   'surged in 2024 as governments '
                                                   'incentivized '
                                                   'entrepreneurship.'}},
                         {'_id': 'vec57',
                          '_score': 0.7917722463607788,
                          'fields': {'chunk_text': 'Startups in 2024 faced tighter '
                                                   'funding conditions as venture '
                                                   'capitalists focused on '
                                                   'profitability over growth.'}},
                         {'_id': 'vec75',
                          '_score': 0.7907494306564331,
                          'fields': {'chunk_text': 'The collapse of Silicon Valley '
                                                   'Bank raised questions about '
                                                   'regulatory oversight in '
                                                   '2024.'}},
                         {'_id': 'vec51',
                          '_score': 0.790622889995575,
                          'fields': {'chunk_text': 'The European Union introduced '
                                                   'new fiscal policies in 2024 '
                                                   'aimed at reducing public debt '
                                                   'without stifling growth.'}},
                         {'_id': 'vec89',
                          '_score': 0.7899052500724792,
                          'fields': {'chunk_text': 'Venture capital investments in '
                                                   '2024 leaned heavily toward AI '
                                                   'and automation startups.'}}]},
     'usage': {'embed_total_tokens': 12, 'read_units': 1}}
    ```
  </Step>

  <Step title="Search by sparse vectors">
    <a />

    Perform a [lexical search](/guides/search/lexical-search) against the index that stores sparse vectors.

    For example, the following code searches that index for 40 records that most exactly match the words in the query. Again, because the index is integrated with an embedding model, you provide the query as text and Pinecone converts the text to a sparse vector automatically.

    ```python Python theme={null}
    sparse_results = sparse_index.search(
        namespace="example-namespace",
        query={
            "top_k": 40,
            "inputs": {
                "text": query
            }
        }
    )

    print(sparse_results)
    ```

    ```python Response [expandable] theme={null}
    {'result': {'hits': [{'_id': 'vec35',
                          '_score': 7.0625,
                          'fields': {'chunk_text': 'Unemployment hit at 2.4% in Q3 '
                                                   'of 2024.'}},
                         {'_id': 'vec46',
                          '_score': 7.041015625,
                          'fields': {'chunk_text': 'Economic recovery in Q2 2024 '
                                                   'relied heavily on government '
                                                   'spending in infrastructure and '
                                                   'green energy projects.'}},
                         {'_id': 'vec36',
                          '_score': 6.96875,
                          'fields': {'chunk_text': 'Unemployment is expected to '
                                                   'hit 2.5% in Q3 of 2024.'}},
                         {'_id': 'vec42',
                          '_score': 6.9609375,
                          'fields': {'chunk_text': 'Tech sector layoffs in Q3 2024 '
                                                   'have reshaped hiring trends '
                                                   'across high-growth '
                                                   'industries.'}},
                         {'_id': 'vec49',
                          '_score': 6.65625,
                          'fields': {'chunk_text': "China's economic growth in "
                                                   '2024 slowed to its lowest '
                                                   'level in decades due to '
                                                   'structural reforms and weak '
                                                   'exports.'}},
                         {'_id': 'vec63',
                          '_score': 6.4765625,
                          'fields': {'chunk_text': 'Population aging emerged as a '
                                                   'critical economic issue in '
                                                   '2024, especially in advanced '
                                                   'economies.'}},
                         {'_id': 'vec92',
                          '_score': 5.72265625,
                          'fields': {'chunk_text': 'Income inequality widened in '
                                                   '2024 despite strong economic '
                                                   'growth in developed nations.'}},
                         {'_id': 'vec52',
                          '_score': 5.599609375,
                          'fields': {'chunk_text': 'Record-breaking weather events '
                                                   'in early 2024 have highlighted '
                                                   'the growing economic impact of '
                                                   'climate change.'}},
                         {'_id': 'vec89',
                          '_score': 4.0078125,
                          'fields': {'chunk_text': 'Venture capital investments in '
                                                   '2024 leaned heavily toward AI '
                                                   'and automation startups.'}},
                         {'_id': 'vec62',
                          '_score': 3.99609375,
                          'fields': {'chunk_text': 'Private equity activity in '
                                                   '2024 focused on renewable '
                                                   'energy and technology sectors '
                                                   'amid shifting investor '
                                                   'priorities.'}},
                         {'_id': 'vec57',
                          '_score': 3.93359375,
                          'fields': {'chunk_text': 'Startups in 2024 faced tighter '
                                                   'funding conditions as venture '
                                                   'capitalists focused on '
                                                   'profitability over growth.'}},
                         {'_id': 'vec69',
                          '_score': 3.8984375,
                          'fields': {'chunk_text': 'The agricultural sector faced '
                                                   'challenges in 2024 due to '
                                                   'extreme weather and rising '
                                                   'input costs.'}},
                         {'_id': 'vec37',
                          '_score': 3.89453125,
                          'fields': {'chunk_text': 'In Q3 2025 unemployment for '
                                                   'the prior year was revised to '
                                                   '2.2%'}},
                         {'_id': 'vec60',
                          '_score': 3.822265625,
                          'fields': {'chunk_text': 'Healthcare spending in 2024 '
                                                   'surged as governments expanded '
                                                   'access to preventive care and '
                                                   'pandemic preparedness.'}},
                         {'_id': 'vec51',
                          '_score': 3.783203125,
                          'fields': {'chunk_text': 'The European Union introduced '
                                                   'new fiscal policies in 2024 '
                                                   'aimed at reducing public debt '
                                                   'without stifling growth.'}},
                         {'_id': 'vec55',
                          '_score': 3.765625,
                          'fields': {'chunk_text': 'Trade tensions between the '
                                                   'U.S. and China escalated in '
                                                   '2024, impacting global supply '
                                                   'chains and investment flows.'}},
                         {'_id': 'vec70',
                          '_score': 3.76171875,
                          'fields': {'chunk_text': 'Consumer spending patterns '
                                                   'shifted in 2024, with a '
                                                   'greater focus on experiences '
                                                   'over goods.'}},
                         {'_id': 'vec90',
                          '_score': 3.70703125,
                          'fields': {'chunk_text': 'The surge in e-commerce in '
                                                   '2024 was facilitated by '
                                                   'advancements in logistics '
                                                   'technology.'}},
                         {'_id': 'vec87',
                          '_score': 3.69140625,
                          'fields': {'chunk_text': "The U.S. labor market's "
                                                   'resilience in 2024 defied '
                                                   'predictions of a severe '
                                                   'recession.'}},
                         {'_id': 'vec78',
                          '_score': 3.673828125,
                          'fields': {'chunk_text': 'Consumer sentiment surveys in '
                                                   '2024 reflected optimism '
                                                   'despite high interest rates.'}},
                         {'_id': 'vec82',
                          '_score': 3.66015625,
                          'fields': {'chunk_text': 'Renewable energy subsidies in '
                                                   '2024 reduced the global '
                                                   'reliance on fossil fuels.'}},
                         {'_id': 'vec53',
                          '_score': 3.642578125,
                          'fields': {'chunk_text': 'Cryptocurrencies faced '
                                                   'regulatory scrutiny in 2024, '
                                                   'leading to volatility and '
                                                   'reduced market '
                                                   'capitalization.'}},
                         {'_id': 'vec94',
                          '_score': 3.625,
                          'fields': {'chunk_text': 'Cyberattacks targeting '
                                                   'financial institutions in 2024 '
                                                   'led to record cybersecurity '
                                                   'spending.'}},
                         {'_id': 'vec45',
                          '_score': 3.607421875,
                          'fields': {'chunk_text': 'Corporate earnings in Q4 2024 '
                                                   'were largely impacted by '
                                                   'rising raw material costs and '
                                                   'currency fluctuations.'}},
                         {'_id': 'vec47',
                          '_score': 3.576171875,
                          'fields': {'chunk_text': 'The housing market saw a '
                                                   'rebound in late 2024, driven '
                                                   'by falling mortgage rates and '
                                                   'pent-up demand.'}},
                         {'_id': 'vec84',
                          '_score': 3.5703125,
                          'fields': {'chunk_text': "The IMF's 2024 global outlook "
                                                   'highlighted risks of '
                                                   'stagflation in emerging '
                                                   'markets.'}},
                         {'_id': 'vec41',
                          '_score': 3.5546875,
                          'fields': {'chunk_text': 'Forecasts of global supply '
                                                   'chain disruptions eased in '
                                                   'late 2024, but consumer prices '
                                                   'remained elevated due to '
                                                   'persistent demand.'}},
                         {'_id': 'vec65',
                          '_score': 3.537109375,
                          'fields': {'chunk_text': 'The global shipping industry '
                                                   'experienced declining freight '
                                                   'rates in 2024 due to '
                                                   'overcapacity and reduced '
                                                   'demand.'}},
                         {'_id': 'vec96',
                          '_score': 3.53125,
                          'fields': {'chunk_text': 'New trade agreements signed '
                                                   '2022 will make an impact in '
                                                   '2024'}},
                         {'_id': 'vec86',
                          '_score': 3.52734375,
                          'fields': {'chunk_text': 'Digital transformation '
                                                   'initiatives in 2024 drove '
                                                   'productivity gains in the '
                                                   'services sector.'}},
                         {'_id': 'vec95',
                          '_score': 3.5234375,
                          'fields': {'chunk_text': 'Automation in agriculture in '
                                                   '2024 increased yields but '
                                                   'displaced rural workers.'}},
                         {'_id': 'vec64',
                          '_score': 3.51171875,
                          'fields': {'chunk_text': 'Rising commodity prices in '
                                                   '2024 strained emerging markets '
                                                   'dependent on imports of raw '
                                                   'materials.'}},
                         {'_id': 'vec79',
                          '_score': 3.51171875,
                          'fields': {'chunk_text': 'The resurgence of industrial '
                                                   'policy in Q1 2024 focused on '
                                                   'decoupling critical supply '
                                                   'chains.'}},
                         {'_id': 'vec66',
                          '_score': 3.48046875,
                          'fields': {'chunk_text': 'Bank lending to small and '
                                                   'medium-sized enterprises '
                                                   'surged in 2024 as governments '
                                                   'incentivized '
                                                   'entrepreneurship.'}},
                         {'_id': 'vec6',
                          '_score': 3.4765625,
                          'fields': {'chunk_text': 'Unemployment hit a record low '
                                                   'of 3.7% in Q4 of 2024.'}},
                         {'_id': 'vec58',
                          '_score': 3.39453125,
                          'fields': {'chunk_text': 'Oil production cuts in Q1 2024 '
                                                   'by OPEC nations drove prices '
                                                   'higher, influencing global '
                                                   'energy policies.'}},
                         {'_id': 'vec80',
                          '_score': 3.390625,
                          'fields': {'chunk_text': 'Technological innovation in '
                                                   'the fintech sector disrupted '
                                                   'traditional banking in 2024.'}},
                         {'_id': 'vec75',
                          '_score': 3.37109375,
                          'fields': {'chunk_text': 'The collapse of Silicon Valley '
                                                   'Bank raised questions about '
                                                   'regulatory oversight in '
                                                   '2024.'}},
                         {'_id': 'vec67',
                          '_score': 3.357421875,
                          'fields': {'chunk_text': 'Renewable energy projects '
                                                   'accounted for a record share '
                                                   'of global infrastructure '
                                                   'investment in 2024.'}},
                         {'_id': 'vec56',
                          '_score': 3.341796875,
                          'fields': {'chunk_text': 'Consumer confidence indices '
                                                   'remained resilient in Q2 2024 '
                                                   'despite fears of an impending '
                                                   'recession.'}}]},
     'usage': {'embed_total_tokens': 9, 'read_units': 1}}
    ```
  </Step>

  <Step title="Merge and deduplicate the results">
    <a />

    Merge the 40 dense and 40 sparse results and deduplicated them based on the field you used to link sparse and dense vectors.

    For example, the following code merges and deduplicates the results based on the `_id` field, resulting in 52 unique results.

    ```python Python theme={null}
    def merge_chunks(h1, h2):
        """Get the unique hits from two search results and return them as single array of {'_id', 'chunk_text'} dicts, printing each dict on a new line."""
        # Deduplicate by _id
        deduped_hits = {hit['_id']: hit for hit in h1['result']['hits'] + h2['result']['hits']}.values()
        # Sort by _score descending
        sorted_hits = sorted(deduped_hits, key=lambda x: x['_score'], reverse=True)
        # Transform to format for reranking
        result = [{'_id': hit['_id'], 'chunk_text': hit['fields']['chunk_text']} for hit in sorted_hits]
        return result

    merged_results = merge_chunks(sparse_results, dense_results)

    print('[\n   ' + ',\n   '.join(str(obj) for obj in merged_results) + '\n]')
    ```

    ```console Response [expandable] theme={null}
    [
       {'_id': 'vec92', 'chunk_text': 'Income inequality widened in 2024 despite strong economic growth in developed nations.'},
       {'_id': 'vec69', 'chunk_text': 'The agricultural sector faced challenges in 2024 due to extreme weather and rising input costs.'},
       {'_id': 'vec70', 'chunk_text': 'Consumer spending patterns shifted in 2024, with a greater focus on experiences over goods.'},
       {'_id': 'vec90', 'chunk_text': 'The surge in e-commerce in 2024 was facilitated by advancements in logistics technology.'},
       {'_id': 'vec78', 'chunk_text': 'Consumer sentiment surveys in 2024 reflected optimism despite high interest rates.'},
       {'_id': 'vec82', 'chunk_text': 'Renewable energy subsidies in 2024 reduced the global reliance on fossil fuels.'},
       {'_id': 'vec94', 'chunk_text': 'Cyberattacks targeting financial institutions in 2024 led to record cybersecurity spending.'},
       {'_id': 'vec65', 'chunk_text': 'The global shipping industry experienced declining freight rates in 2024 due to overcapacity and reduced demand.'},
       {'_id': 'vec86', 'chunk_text': 'Digital transformation initiatives in 2024 drove productivity gains in the services sector.'},
       {'_id': 'vec95', 'chunk_text': 'Automation in agriculture in 2024 increased yields but displaced rural workers.'},
       {'_id': 'vec80', 'chunk_text': 'Technological innovation in the fintech sector disrupted traditional banking in 2024.'},
       {'_id': 'vec67', 'chunk_text': 'Renewable energy projects accounted for a record share of global infrastructure investment in 2024.'},
       {'_id': 'vec35', 'chunk_text': 'Unemployment hit at 2.4% in Q3 of 2024.'},
       {'_id': 'vec36', 'chunk_text': 'Unemployment is expected to hit 2.5% in Q3 of 2024.'},
       {'_id': 'vec6', 'chunk_text': 'Unemployment hit a record low of 3.7% in Q4 of 2024.'},
       {'_id': 'vec42', 'chunk_text': 'Tech sector layoffs in Q3 2024 have reshaped hiring trends across high-growth industries.'},
       {'_id': 'vec48', 'chunk_text': 'Wage growth outpaced inflation for the first time in years, signaling improved purchasing power in 2024.'},
       {'_id': 'vec55', 'chunk_text': 'Trade tensions between the U.S. and China escalated in 2024, impacting global supply chains and investment flows.'},
       {'_id': 'vec45', 'chunk_text': 'Corporate earnings in Q4 2024 were largely impacted by rising raw material costs and currency fluctuations.'},
       {'_id': 'vec72', 'chunk_text': 'In early 2024, global GDP growth slowed, driven by weaker exports in Asia and Europe.'},
       {'_id': 'vec29', 'chunk_text': 'Growth vs. value investing strategies in 2024.'},
       {'_id': 'vec46', 'chunk_text': 'Economic recovery in Q2 2024 relied heavily on government spending in infrastructure and green energy projects.'},
       {'_id': 'vec79', 'chunk_text': 'The resurgence of industrial policy in Q1 2024 focused on decoupling critical supply chains.'},
       {'_id': 'vec87', 'chunk_text': "The U.S. labor market's resilience in 2024 defied predictions of a severe recession."},
       {'_id': 'vec40', 'chunk_text': 'Labor market trends show a declining participation rate despite record low unemployment in 2024.'},
       {'_id': 'vec37', 'chunk_text': 'In Q3 2025 unemployment for the prior year was revised to 2.2%'},
       {'_id': 'vec58', 'chunk_text': 'Oil production cuts in Q1 2024 by OPEC nations drove prices higher, influencing global energy policies.'},
       {'_id': 'vec47', 'chunk_text': 'The housing market saw a rebound in late 2024, driven by falling mortgage rates and pent-up demand.'},
       {'_id': 'vec41', 'chunk_text': 'Forecasts of global supply chain disruptions eased in late 2024, but consumer prices remained elevated due to persistent demand.'},
       {'_id': 'vec56', 'chunk_text': 'Consumer confidence indices remained resilient in Q2 2024 despite fears of an impending recession.'},
       {'_id': 'vec63', 'chunk_text': 'Population aging emerged as a critical economic issue in 2024, especially in advanced economies.'},
       {'_id': 'vec52', 'chunk_text': 'Record-breaking weather events in early 2024 have highlighted the growing economic impact of climate change.'},
       {'_id': 'vec23', 'chunk_text': 'Top SPAC mergers in the technology sector for 2024.'},
       {'_id': 'vec62', 'chunk_text': 'Private equity activity in 2024 focused on renewable energy and technology sectors amid shifting investor priorities.'},
       {'_id': 'vec64', 'chunk_text': 'Rising commodity prices in 2024 strained emerging markets dependent on imports of raw materials.'},
       {'_id': 'vec54', 'chunk_text': 'The global tourism sector showed signs of recovery in late 2024 after years of pandemic-related setbacks.'},
       {'_id': 'vec96', 'chunk_text': 'New trade agreements signed 2022 will make an impact in 2024'},
       {'_id': 'vec49', 'chunk_text': "China's economic growth in 2024 slowed to its lowest level in decades due to structural reforms and weak exports."},
       {'_id': 'vec7', 'chunk_text': 'The CPI index rose by 6% in July 2024, raising concerns about purchasing power.'},
       {'_id': 'vec84', 'chunk_text': "The IMF's 2024 global outlook highlighted risks of stagflation in emerging markets."},
       {'_id': 'vec13', 'chunk_text': 'Credit card APRs reached an all-time high of 22.8% in 2024.'},
       {'_id': 'vec53', 'chunk_text': 'Cryptocurrencies faced regulatory scrutiny in 2024, leading to volatility and reduced market capitalization.'},
       {'_id': 'vec60', 'chunk_text': 'Healthcare spending in 2024 surged as governments expanded access to preventive care and pandemic preparedness.'},
       {'_id': 'vec91', 'chunk_text': 'The impact of ESG investing on corporate strategies has been a major focus in 2024.'},
       {'_id': 'vec68', 'chunk_text': 'Cybersecurity spending reached new highs in 2024, reflecting the growing threat of digital attacks on infrastructure.'},
       {'_id': 'vec59', 'chunk_text': 'The adoption of digital currencies by central banks increased in 2024, reshaping monetary policy frameworks.'},
       {'_id': 'vec39', 'chunk_text': 'The rise in energy prices significantly impacted inflation trends during the first half of 2024.'},
       {'_id': 'vec66', 'chunk_text': 'Bank lending to small and medium-sized enterprises surged in 2024 as governments incentivized entrepreneurship.'},
       {'_id': 'vec57', 'chunk_text': 'Startups in 2024 faced tighter funding conditions as venture capitalists focused on profitability over growth.'},
       {'_id': 'vec75', 'chunk_text': 'The collapse of Silicon Valley Bank raised questions about regulatory oversight in 2024.'},
       {'_id': 'vec51', 'chunk_text': 'The European Union introduced new fiscal policies in 2024 aimed at reducing public debt without stifling growth.'},
       {'_id': 'vec89', 'chunk_text': 'Venture capital investments in 2024 leaned heavily toward AI and automation startups.'}
    ]
    ```
  </Step>

  <Step title="Rerank the results">
    <a />

    Use one of Pinecone's [hosted reranking models](/guides/search/rerank-results#reranking-models) to rerank the merged and deduplicated results based on a unified relevance score and then return a smaller set of the most highly relevant results.

    For example, the following code sends the 52 unique results from the last step to the `bge-reranker-v2-m3` reranking model and returns the top 10 most relevant results.

    ```python Python theme={null}
    result = pc.inference.rerank(
        model="bge-reranker-v2-m3",
        query=query,
        documents=merged_results,
        rank_fields=["chunk_text"],
        top_n=10,
        return_documents=True,
        parameters={
            "truncate": "END"
        }
    )

    print("Query", query)
    print('-----')
    for row in result.data:
        print(f"{row['document']['_id']} - {round(row['score'], 2)} - {row['document']['chunk_text']}")
    ```

    ```console Response [expandable] theme={null}
    Query Q3 2024 us economic data
    -----
    vec36 - 0.84 - Unemployment is expected to hit 2.5% in Q3 of 2024.
    vec35 - 0.76 - Unemployment hit at 2.4% in Q3 of 2024.
    vec48 - 0.33 - Wage growth outpaced inflation for the first time in years, signaling improved purchasing power in 2024.
    vec37 - 0.25 - In Q3 2025 unemployment for the prior year was revised to 2.2%
    vec42 - 0.21 - Tech sector layoffs in Q3 2024 have reshaped hiring trends across high-growth industries.
    vec87 - 0.2 - The U.S. labor market's resilience in 2024 defied predictions of a severe recession.
    vec63 - 0.08 - Population aging emerged as a critical economic issue in 2024, especially in advanced economies.
    vec92 - 0.08 - Income inequality widened in 2024 despite strong economic growth in developed nations.
    vec72 - 0.07 - In early 2024, global GDP growth slowed, driven by weaker exports in Asia and Europe.
    vec46 - 0.06 - Economic recovery in Q2 2024 relied heavily on government spending in infrastructure and green energy projects.
    ```
  </Step>
</Steps>


# Lexical search
Source: https://docs.pinecone.io/guides/search/lexical-search

Run sparse-vector lexical search in Pinecone with custom sparse encoders like pinecone-sparse-english-v0 for token-weighted keyword retrieval.

This page shows you how to search an [index with sparse vectors](/guides/index-data/indexing-overview#sparse-indexes) for records that most exactly match the words or phrases in a query. This is often called sparse-vector lexical search.

<Note>
  For general-purpose text retrieval (product search, content discovery, document Q\&A), we recommend [full-text search](/guides/search/full-text-search). Full-text search runs over `string` fields you've declared with `full_text_search` enabled, using BM25 ranking and Lucene query syntax. The multi-field schema also lets you add `dense_vector` or `sparse_vector` ranking later in the same index.

  Sparse-vector lexical search (this page) is a distinct retrieval mode. Reach for it when your retrieval target is a token-weighted signal you already produce upstream of Pinecone, for example, when you're using a custom sparse encoder such as [`pinecone-sparse-english-v0`](/models/pinecone-sparse-english-v0), or when your application owns the sparse-vector representation directly.
</Note>

Lexical search uses [sparse vectors](https://www.pinecone.io/learn/sparse-retrieval/), which have a very large number of dimensions, where only a small proportion of values are non-zero. The dimensions represent words from a dictionary, and the values represent the importance of these words in the document. Words are scored independently and then summed, with the most similar records scored highest.

## Search with text

<Note>
  Searching with text is supported only for [indexes with integrated embedding](/guides/index-data/indexing-overview#integrated-embedding).
</Note>

To search an index of sparse vectors with a query text, use the [`search_records`](/reference/api/latest/data-plane/search_records) operation with the following parameters:

* `namespace`: The [namespace](/guides/index-data/indexing-overview#namespaces) to query. To use the default namespace, set to `"__default__"`.
* `query.inputs.text`:  The query text. Pinecone uses the [embedding model](/guides/index-data/create-an-index#embedding-models) integrated with the index to convert the text to a sparse vector automatically.
* `query.top_k`:  The number of records to return.
* `query.match_terms`: (Optional) A list of terms that must be present in each search result. For more details, see [Filter by required terms](#filter-by-required-terms).
* `fields`: (Optional) The fields to return in the response. If not specified, the response includes all fields.

For example, the following code converts the query “What is AAPL's outlook, considering both product launches and market conditions?” to a sparse vector and then searches for the 3 most similar vectors in the `example-namespace` namespace:

<CodeGroup>
  ```python Python theme={null}
  from pinecone import Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")

  # To get the unique host for an index, 
  # see https://docs.pinecone.io/guides/manage-data/target-an-index
  index = pc.Index(host="INDEX_HOST")

  results = index.search(
      namespace="example-namespace", 
      query={
          "inputs": {"text": "What is AAPL's outlook, considering both product launches and market conditions?"}, 
          "top_k": 3
      },
      fields=["chunk_text", "quarter"]
  )

  print(results)
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone'

  const pc = new Pinecone({ apiKey: "YOUR_API_KEY" })

  // To get the unique host for an index, 
  // see https://docs.pinecone.io/guides/manage-data/target-an-index
  const namespace = pc.index("INDEX_NAME", "INDEX_HOST").namespace("example-namespace");

  const response = await namespace.searchRecords({
    query: {
      topK: 3,
      inputs: { text: "What is AAPL's outlook, considering both product launches and market conditions?" },
    },
    fields: ['chunk_text', 'quarter']
  });

  console.log(response);
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Index;
  import io.pinecone.configs.PineconeConfig;
  import io.pinecone.configs.PineconeConnection;
  import org.openapitools.db_data.client.ApiException;
  import org.openapitools.db_data.client.model.SearchRecordsResponse;

  import java.util.*;

  public class SearchText {
      public static void main(String[] args) throws ApiException {
          PineconeConfig config = new PineconeConfig("YOUR_API_KEY");
          // To get the unique host for an index, 
          // see https://docs.pinecone.io/guides/manage-data/target-an-index
          config.setHost("INDEX_HOST");
          PineconeConnection connection = new PineconeConnection(config);

          Index index = new Index(config, connection, "integrated-sparse-java");

          String query = "What is AAPL's outlook, considering both product launches and market conditions?";
          List<String> fields = new ArrayList<>();
          fields.add("category");
          fields.add("chunk_text");

          // Search the index
          SearchRecordsResponse recordsResponse = index.searchRecordsByText(query,  "example-namespace", fields, 3, null, null);

          // Print the results
          System.out.println(recordsResponse);
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "encoding/json"
      "fmt"
      "log"

      "github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func prettifyStruct(obj interface{}) string {
    	bytes, _ := json.MarshalIndent(obj, "", "  ")
      return string(bytes)
  }

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

      // To get the unique host for an index, 
      // see https://docs.pinecone.io/guides/manage-data/target-an-index
      idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST", Namespace: "example-namespace"})
      if err != nil {
          log.Fatalf("Failed to create IndexConnection for Host: %v", err)
      } 

      res, err := idxConnection.SearchRecords(ctx, &pinecone.SearchRecordsRequest{
          Query: pinecone.SearchRecordsQuery{
              TopK: 3,
              Inputs: &map[string]interface{}{
                  "text": "What is AAPL's outlook, considering both product launches and market conditions?",
              },
          },
          Fields: &[]string{"chunk_text", "category"},
      })
      if err != nil {
          log.Fatalf("Failed to search records: %v", err)
      }
      fmt.Printf(prettifyStruct(res))
  }
  ```

  ```shell curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  INDEX_HOST="INDEX_HOST"

  curl "https://$INDEX_HOST/records/namespaces/example-namespace/search" \
    -H "Content-Type: application/json" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2025-10" \
    -d '{
          "query": {
            "inputs": { "text": "What is AAPL'\''s outlook, considering both product launches and market conditions?" },
            "top_k": 3
          },
          "fields": ["chunk_text", "quarter"]
      }'
  ```
</CodeGroup>

The results will look as follows. The most similar records are scored highest.

<CodeGroup>
  ```python Python theme={null}
  {'result': {'hits': [{'_id': 'vec2',
                        '_score': 10.77734375,
                        'fields': {'chunk_text': "Analysts suggest that AAPL'''s "
                                                 'upcoming Q4 product launch '
                                                 'event might solidify its '
                                                 'position in the premium '
                                                 'smartphone market.',
                                   'quarter': 'Q4'}},
                       {'_id': 'vec3',
                        '_score': 6.49066162109375,
                        'fields': {'chunk_text': "AAPL'''s strategic Q3 "
                                                 'partnerships with '
                                                 'semiconductor suppliers could '
                                                 'mitigate component risks and '
                                                 'stabilize iPhone production.',
                                   'quarter': 'Q3'}},
                       {'_id': 'vec1',
                        '_score': 5.3671875,
                        'fields': {'chunk_text': 'AAPL reported a year-over-year '
                                                 'revenue increase, expecting '
                                                 'stronger Q3 demand for its '
                                                 'flagship phones.',
                                   'quarter': 'Q3'}}]},
   'usage': {'embed_total_tokens': 18, 'read_units': 1}}
  ```

  ```javascript JavaScript theme={null}
  {
    result: { 
      hits: [ 
        {
          _id: "vec2",
          _score: 10.82421875,
          fields: {
            chunk_text: "Analysts suggest that AAPL'''s upcoming Q4 product launch event might solidify its position in the premium smartphone market.",
            quarter: "Q4"
          }
        },
        {
          _id: "vec3",
          _score: 6.49066162109375,
          fields: {
            chunk_text: "AAPL'''s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production.",
            quarter: "Q3"
          }
        },
        {
          _id: "vec1",
          _score: 5.3671875,
          fields: {
            chunk_text: "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.",
            quarter: "Q3"
          }
        }
      ]
    },
    usage: { 
      readUnits: 1, 
      embedTotalTokens: 18 
    }
  }
  ```

  ```java Java theme={null}
  class SearchRecordsResponse {
      result: class SearchRecordsResponseResult {
          hits: [class Hit {
              id: vec2
              score: 10.82421875
              fields: {chunk_text=Analysts suggest that AAPL's upcoming Q4 product launch event might solidify its position in the premium smartphone market., quarter=Q4}
              additionalProperties: null
          }, class Hit {
              id: vec3
              score: 6.49066162109375
              fields: {chunk_text=AAAPL'''s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production., quarter=Q3}
              additionalProperties: null
          }, class Hit {
              id: vec1
              score: 5.3671875
              fields: {chunk_text=AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones., quarter=Q3}
              additionalProperties: null
          }]
          additionalProperties: null
      }
      usage: class SearchUsage {
          readUnits: 1
          embedTotalTokens: 18
      }
      additionalProperties: null
  }
  ```

  ```go Go theme={null}
  {
    "result": {
      "hits": [
        {
          "_id": "vec2",
          "_score": 10.833984,
          "fields": {
            "chunk_text": "Analysts suggest that AAPL's upcoming Q4 product launch event might solidify its position in the premium smartphone market.",
            "quarter": "Q4"
          }
        },
        {
          "_id": "vec3",
          "_score": 6.473572,
          "fields": {
            "chunk_text": "AAPL's strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production.",
            "quarter": "Q3"
          }
        },
        {
          "_id": "vec1",
          "_score": 5.3710938,
          "fields": {
            "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.",
            "quarter": "Q3"
          }
        }
      ]
    },
    "usage": {
      "read_units": 6,
      "embed_total_tokens": 18
    }
  }
  ```

  ```json curl theme={null}
  {
    "result": {
      "hits": [
        {
          "_id": "vec2",
          "_score": 10.82421875,
          "fields": {
            "chunk_text": "Analysts suggest that AAPL'''s upcoming Q4 product launch event might solidify its position in the premium smartphone market.",
            "quarter": "Q4"
          }
        },
        {
          "_id": "vec3",
          "_score": 6.49066162109375,
          "fields": {
            "chunk_text": "AAPL'''s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production.",
            "quarter": "Q3"
          }
        },
        {
          "_id": "vec1",
          "_score": 5.3671875,
          "fields": {
            "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.",
            "quarter": "Q3"
          }
        }
      ]
    },
    "usage": {
      "embed_total_tokens": 18,
      "read_units": 1
    }
  }
  ```
</CodeGroup>

## Search with a sparse vector

To search an index of sparse vectors with a sparse vector representation of a query, use the [`query`](/reference/api/latest/data-plane/query) operation with the following parameters:

* `namespace`: The [namespace](/guides/index-data/indexing-overview#namespaces) to query. To use the default namespace, set to `"__default__"`.
* `sparse_vector`: The sparse vector values and indices.
* `top_k`: The number of results to return.
* `include_values`: Whether to include the vector values of the matching records in the response. Defaults to `false`.
* `include_metadata`: Whether to include the metadata of the matching records in the response. Defaults to `false`.

<Note>
  When querying with `top_k` over 1000, for optimal performance set `include_values=false` and `include_metadata=false` to return only IDs and scores.

  Since vectors values are retrieved from object storage, include them in your query results only when you need them (especially with higher `top_k` values). For details, see [Decrease latency](/guides/optimize/decrease-latency#avoid-including-vector-values-when-not-needed).
</Note>

For example, the following code uses a sparse vector representation of the query "What is AAPL's outlook, considering both product launches and market conditions?" to search for the 3 most similar vectors in the `example-namespace` namespace:

<CodeGroup>
  ```python Python theme={null}
  from pinecone import Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")

  # To get the unique host for an index, 
  # see https://docs.pinecone.io/guides/manage-data/target-an-index
  index = pc.Index(host="INDEX_HOST")

  results = index.query(
      namespace="example-namespace",
      sparse_vector={
        "values": [1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0],
        "indices": [767227209, 1640781426, 1690623792, 2021799277, 2152645940, 2295025838, 2443437770, 2779594451, 2956155693, 3476647774, 3818127854, 4283091697]
      }, 
      top_k=3,
      include_metadata=True,
      include_values=False
  )

  print(results)
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone'

  const pc = new Pinecone({ apiKey: "YOUR_API_KEY" })

  // To get the unique host for an index, 
  // see https://docs.pinecone.io/guides/manage-data/target-an-index
  const index = pc.index("INDEX_NAME", "INDEX_HOST")

  const queryResponse = await index.namespace('example-namespace').query({
      sparseVector: {
          indices: [767227209, 1640781426, 1690623792, 2021799277, 2152645940, 2295025838, 2443437770, 2779594451, 2956155693, 3476647774, 3818127854, 4283091697],
          values: [1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0]
      },
      topK: 3,
      includeValues: false,
      includeMetadata: true
  });

  console.log(queryResponse);
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Pinecone;
  import io.pinecone.unsigned_indices_model.QueryResponseWithUnsignedIndices;
  import io.pinecone.clients.Index;

  import java.util.*;

  public class SearchSparseIndex {
      public static void main(String[] args) throws InterruptedException {
          // Instantiate Pinecone class
          Pinecone pinecone = new Pinecone.Builder("YOUR_API_KEY").build();

          String indexName = "docs-example";

          Index index = pinecone.getIndexConnection(indexName);

          List<Long> sparseIndices = Arrays.asList(
                  767227209L, 1640781426L, 1690623792L, 2021799277L, 2152645940L,
                  2295025838L, 2443437770L, 2779594451L, 2956155693L, 3476647774L,
                  3818127854L, 428309169L);
          List<Float> sparseValues = Arrays.asList(
                  1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f,
                  1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f);

          QueryResponseWithUnsignedIndices queryResponse = index.query(3, null, sparseIndices, sparseValues, null, "example-namespace", null, false, true);
          System.out.println(queryResponse);
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
  	"context"
  	"encoding/json"
  	"fmt"
  	"log"

  	"github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func prettifyStruct(obj interface{}) string {
  	bytes, _ := json.MarshalIndent(obj, "", "  ")
  	return string(bytes)
  }

  func main() {
  	ctx := context.Background()

  	pc, err := pinecone.NewClient(pinecone.NewClientParams{
  		ApiKey: "YOUR_API_KEY",
  	})
  	if err != nil {
  		log.Fatalf("Failed to create Client: %v", err)
  	}

  	// To get the unique host for an index,
  	// see https://docs.pinecone.io/guides/manage-data/target-an-index
  	idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST", Namespace: "example-namespace"})
  	if err != nil {
  		log.Fatalf("Failed to create IndexConnection for Host: %v", err)
  	}

  	sparseValues := pinecone.SparseValues{
  		Indices: []uint32{767227209, 1640781426, 1690623792, 2021799277, 2152645940, 2295025838, 2443437770, 2779594451, 2956155693, 3476647774, 3818127854, 4283091697},
  		Values:  []float32{1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0},
  	}

  	res, err := idxConnection.QueryByVectorValues(ctx, &pinecone.QueryByVectorValuesRequest{
  		SparseValues:    &sparseValues,
  		TopK:            3,
  		IncludeValues:   false,
  		IncludeMetadata: true,
  	})
  	if err != nil {
  		log.Fatalf("Error encountered when querying by vector: %v", err)
  	} else {
  		fmt.Printf(prettifyStruct(res))
  	}
  }
  ```

  ```shell curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  INDEX_HOST="INDEX_HOST"

  curl "https://$INDEX_HOST/query" \
    -H "Content-Type: application/json" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2025-10" \
    -d '{
          "sparseVector": {
              "values": [1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0],
              "indices": [767227209, 1640781426, 1690623792, 2021799277, 2152645940, 2295025838, 2443437770, 2779594451, 2956155693, 3476647774, 3818127854, 4283091697]
          },
          "namespace": "example-namespace",
          "topK": 4,
          "includeMetadata": true,
          "includeValues": false
      }'
  ```
</CodeGroup>

The results will look as follows. The most similar records are scored highest.

<CodeGroup>
  ```python Python theme={null}
  {'matches': [{'id': 'vec2',
                'metadata': {'category': 'technology',
                             'quarter': 'Q4',
                             'chunk_text': "Analysts suggest that AAPL'''s "
                                            'upcoming Q4 product launch event '
                                            'might solidify its position in the '
                                            'premium smartphone market.'},
                'score': 10.9042969,
                'values': []},
               {'id': 'vec3',
                'metadata': {'category': 'technology',
                             'quarter': 'Q3',
                             'chunk_text': "AAPL'''s strategic Q3 partnerships "
                                            'with semiconductor suppliers could '
                                            'mitigate component risks and '
                                            'stabilize iPhone production'},
                'score': 6.48010254,
                'values': []},
               {'id': 'vec1',
                'metadata': {'category': 'technology',
                             'quarter': 'Q3',
                             'chunk_text': 'AAPL reported a year-over-year '
                                            'revenue increase, expecting '
                                            'stronger Q3 demand for its flagship '
                                            'phones.'},
                'score': 5.3671875,
                'values': []}],
   'namespace': 'example-namespace',
   'usage': {'read_units': 1}}
  ```

  ```javascript JavaScript theme={null}
  { 
    matches: [
              { 
                id: 'vec2',
                score: 10.9042969,
                values: [],
                metadata: {
                  chunk_text: "Analysts suggest that AAPL'''s upcoming Q4 product launch event might solidify its position in the premium smartphone market.",
                  category: 'technology',
                  quarter: 'Q4'
                }
              },
              {
                id: 'vec3',
                score: 6.48010254,
                values: [],
                metadata: {
                  chunk_text: "AAPL'''s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production.",
                  category: 'technology',
                  quarter: 'Q3'
                }
              },
              {
                id: 'vec1',
                score: 5.3671875,
                values: [],
                metadata: {
                    chunk_text: 'AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.',
                    category: 'technology',
                    quarter: 'Q3'
                }
              }
            ],
    namespace: 'example-namespace',
    usage: {readUnits: 1}
  }
  ```

  ```java Java theme={null}
  class QueryResponseWithUnsignedIndices {
      matches: [ScoredVectorWithUnsignedIndices {
          score: 10.34375
          id: vec2
          values: []
          metadata: fields {
            key: "category"
            value {
              string_value: "technology"
            }
          }
          fields {
            key: "chunk_text"
            value {
              string_value: "Analysts suggest that AAPL\'\\\'\'s upcoming Q4 product launch event might solidify its position in the premium smartphone market."
            }
          }
          fields {
            key: "quarter"
            value {
              string_value: "Q4"
            }
          }
          
          sparseValuesWithUnsignedIndices: SparseValuesWithUnsignedIndices {
              indicesWithUnsigned32Int: []
              values: []
          }
      }, ScoredVectorWithUnsignedIndices {
          score: 5.8638916
          id: vec3
          values: []
          metadata: fields {
            key: "category"
            value {
              string_value: "technology"
            }
          }
          fields {
            key: "chunk_text"
            value {
              string_value: "AAPL\'\\\'\'s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production"
            }
          }
          fields {
            key: "quarter"
            value {
              string_value: "Q3"
            }
          }
          
          sparseValuesWithUnsignedIndices: SparseValuesWithUnsignedIndices {
              indicesWithUnsigned32Int: []
              values: []
          }
      }, ScoredVectorWithUnsignedIndices {
          score: 5.3671875
          id: vec1
          values: []
          metadata: fields {
            key: "category"
            value {
              string_value: "technology"
            }
          }
          fields {
            key: "chunk_text"
            value {
              string_value: "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones."
            }
          }
          fields {
            key: "quarter"
            value {
              string_value: "Q3"
            }
          }
          
          sparseValuesWithUnsignedIndices: SparseValuesWithUnsignedIndices {
              indicesWithUnsigned32Int: []
              values: []
          }
      }]
      namespace: example-namespace
      usage: read_units: 1

  }
  ```

  ```go Go theme={null}
  {
    "matches": [
      {
        "vector": {
          "id": "vec2",
          "metadata": {
            "category": "technology",
            "quarter": "Q4",
            "chunk_text": "Analysts suggest that AAPL's upcoming Q4 product launch event might solidify its position in the premium smartphone market."
          }
        },
        "score": 10.904296
      },
      {
        "vector": {
          "id": "vec3",
          "metadata": {
            "category": "technology",
            "quarter": "Q3",
            "chunk_text": "AAPL's strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production"
          }
        },
        "score": 6.4801025
      },
      {
        "vector": {
          "id": "vec1",
          "metadata": {
            "category": "technology",
            "quarter": "Q3",
            "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones"
          }
        },
        "score": 5.3671875
      }
    ],
    "usage": {
      "read_units": 1
    },
    "namespace": "example-namespace"
  }
  ```

  ```json curl theme={null}
  {
    "results": [],
    "matches": [
      {
        "id": "vec2",
        "score": 10.9042969,
        "values": [],
        "metadata": {
          "chunk_text": "Analysts suggest that AAPL'''s upcoming Q4 product launch event might solidify its position in the premium smartphone market.",
          "category": "technology",
          "quarter": "Q4"
        }
      },
      {
        "id": "vec3",
        "score": 6.48010254,
        "values": [],
        "metadata": {
          "chunk_text": "AAPL'''s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production.",
          "category": "technology",
          "quarter": "Q3"
        }
      },
      {
        "id": "vec1",
        "score": 5.3671875,
        "values": [],
        "metadata": {
            "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.",
            "category": "technology",
            "quarter": "Q3"
        }
      }
    ],
    "namespace": "example-namespace",
    "usage": {
      "readUnits": 1
    }
  }
  ```
</CodeGroup>

## Search with a record ID

When you search with a record ID, Pinecone uses the sparse vector associated with the record as the query. To search an index of sparse vectors with a record ID, use the [`query`](/reference/api/latest/data-plane/query) operation with the following parameters:

* `namespace`: The [namespace](/guides/index-data/indexing-overview#namespaces) to query. To use the default namespace, set to `"__default__"`.
* `id`: The unique record ID containing the sparse vector to use as the query.
* `top_k`: The number of results to return.
* `include_values`: Whether to include the vector values of the matching records in the response. Defaults to `false`.
* `include_metadata`: Whether to include the metadata of the matching records in the response. Defaults to `false`.

<Note>
  When querying with `top_k` over 1000, for optimal performance set `include_values=false` and `include_metadata=false` to return only IDs and scores.

  Since vectors values are retrieved from object storage, include them in your query results only when you need them (especially with higher `top_k` values). For details, see [Decrease latency](/guides/optimize/decrease-latency#avoid-including-vector-values-when-not-needed).
</Note>

For example, the following code uses an ID to search for the 3 records in the `example-namespace` namespace that best match the sparse vector in the record:

<CodeGroup>
  ```Python Python theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")

  # To get the unique host for an index, 
  # see https://docs.pinecone.io/guides/manage-data/target-an-index
  index = pc.Index(host="INDEX_HOST")

  index.query(
      namespace="example-namespace",
      id="rec2", 
      top_k=3,
      include_metadata=True,
      include_values=False
  )
  ```

  ```JavaScript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone'

  const pc = new Pinecone({ apiKey: "YOUR_API_KEY" })

  // To get the unique host for an index, 
  // see https://docs.pinecone.io/guides/manage-data/target-an-index
  const index = pc.index("INDEX_NAME", "INDEX_HOST")

  const queryResponse = await index.namespace('example-namespace').query({
      id: 'rec2',
      topK: 3,
      includeValues: false,
      includeMetadata: true,
  });
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Index;
  import io.pinecone.configs.PineconeConfig;
  import io.pinecone.configs.PineconeConnection;
  import io.pinecone.unsigned_indices_model.QueryResponseWithUnsignedIndices;

  public class QueryExample {
      public static void main(String[] args) {
          PineconeConfig config = new PineconeConfig("YOUR_API_KEY");
          // To get the unique host for an index, 
          // see https://docs.pinecone.io/guides/manage-data/target-an-index
          config.setHost("INDEX_HOST");
          PineconeConnection connection = new PineconeConnection(config);
          Index index = new Index(connection, "INDEX_NAME");
          QueryResponseWithUnsignedIndices queryRespone = index.queryByVectorId(3, "rec2", "example-namespace", null, false, true);
          System.out.println(queryResponse);
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "encoding/json"
      "fmt"
      "log"

      "github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func prettifyStruct(obj interface{}) string {
  	bytes, _ := json.MarshalIndent(obj, "", "  ")
  	return string(bytes)
  }

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

      // To get the unique host for an index, 
      // see https://docs.pinecone.io/guides/manage-data/target-an-index
      idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST", Namespace: "example-namespace"})
      if err != nil {
          log.Fatalf("Failed to create IndexConnection for Host: %v", err)
    	}

      vectorId := "rec2"
      res, err := idxConnection.QueryByVectorId(ctx, &pinecone.QueryByVectorIdRequest{
          VectorId:      vectorId,
          TopK:          3,
          IncludeValues: false,
          IncludeMetadata: true,
      })
      if err != nil {
          log.Fatalf("Error encountered when querying by vector ID `%v`: %v", vectorId, err)
      } else {
          fmt.Printf(prettifyStruct(res.Matches))
      }
  }
  ```

  ```bash curl theme={null}
  # To get the unique host for an index,
  # see https://docs.pinecone.io/guides/manage-data/target-an-index
  PINECONE_API_KEY="YOUR_API_KEY"
  INDEX_HOST="INDEX_HOST"

  curl "https://$INDEX_HOST/query" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H 'Content-Type: application/json' \
    -H "X-Pinecone-Api-Version: 2025-10" \
    -d '{
          "id": "rec2",
          "namespace": "example-namespace",
          "topK": 3,
          "includeMetadata": true,
          "includeValues": false
      }'
  ```
</CodeGroup>

## Filter by required terms

<Note>
  This feature is in [public preview](/release-notes/feature-availability) and is available only on the `2025-10` version of the API. See [limitations](#limitations) for details.
</Note>

When [searching with text](#search-with-text), you can specify a list of terms that must be present in each lexical search result. This is especially useful for:

* **Precision filtering**: Ensuring specific entities or concepts appear in results
* **Quality control**: Filtering out results that don't contain essential keywords
* **Domain-specific searches**: Requiring domain-specific terminology in results
* **Entity-based filtering**: Ensuring specific people, places, or things are mentioned

To filter by required terms, add `match_terms` to your query, specifying the `terms` to require and the `strategy` to use. Currently, `all` is the only strategy supported (all terms must be present).

For example, the following request searches for records about Tesla's stock performance while ensuring both "Tesla" and "stock" appear in each result:

```bash curl theme={null}
PINECONE_API_KEY="YOUR_API_KEY"
INDEX_HOST="INDEX_HOST"

curl "https://$INDEX_HOST/records/namespaces/example-namespace/search" \
  -H "Content-Type: application/json" \
  -H "Api-Key: $PINECONE_API_KEY" \
  -H "X-Pinecone-Api-Version: unstable" \
  -d '{
        "query": {
          "inputs": { "text": "What is the current outlook for Tesla stock performance?" },
          "top_k": 3,
          "match_terms": {
            "terms": ["Tesla", "stock"],
            "strategy": "all"
          }
        },
        "fields": ["chunk_text"]
    }'
```

The response includes only records that contain both "Tesla" and "stock":

```json theme={null}
{
  "result": {
    "hits": [
      {
        "_id": "tesla_q4_earnings",
        "_score": 9.82421875,
        "fields": {
          "chunk_text": "Tesla stock surged 8% in after-hours trading following strong Q4 earnings that exceeded analyst expectations. The company reported record vehicle deliveries and improved profit margins."
        }
      },
      {
        "_id": "tesla_competition_analysis",
        "_score": 7.49066162109375,
        "fields": {
          "chunk_text": "Tesla stock faces increasing competition from traditional automakers entering the electric vehicle market. However, analysts maintain that Tesla's technological lead and brand recognition provide significant advantages."
        }
      },
      {
        "_id": "tesla_production_update",
        "_score": 6.3671875,
        "fields": {
          "chunk_text": "Tesla stock performance is closely tied to production capacity at its Gigafactories. Recent expansion announcements suggest the company is positioning for continued growth in global markets."
        }
      }
    ]
  },
  "usage": {
    "embed_total_tokens": 18,
    "read_units": 1
  }
}
```

Without the `match_terms` filter, you might get results like:

* "Tesla cars are popular in California" (mentions Tesla but not stock)
* "Stock market volatility affects tech companies" (mentions stock but not Tesla)
* "Electric vehicle sales are growing" (neither Tesla nor stock)

### Limitations

* **Integrated indexes only**: Filtering by required terms is supported only for [indexes with integrated embedding](/guides/index-data/indexing-overview#integrated-embedding).
* **Post-processing filter**: The filtering happens after the initial query, so potential matches that weren't included in the initial `top_k` results won't appear in the final results
* **No phrase matching**: Terms are matched individually in any order and location.
* **No case-sensitivity**: Terms are normalized during processing.


# Reciprocal rank fusion
Source: https://docs.pinecone.io/guides/search/reciprocal-rank-fusion

Combine results from separate Pinecone searches into a single ranking with reciprocal rank fusion (RRF), a client-side method that fuses rankings, not scores.

<Note>
  The examples below use the [document API](/guides/search/full-text-search), which is in [public preview](/guides/search/full-text-search#public-preview). Reciprocal rank fusion itself is a client-side method and works with the results of any Pinecone search.
</Note>

When you rank the same set of documents two different ways, for example, a [full-text (BM25) search](/guides/search/full-text-search) and a [semantic (dense-vector) search](/guides/search/semantic-search), the scores live on different, incomparable scales. Adding or averaging the raw scores is not meaningful, and one signal usually dominates. **Reciprocal rank fusion (RRF)** combines them by fusing the *rankings* instead of the scores, so no normalization or per-signal weighting is required.

Today, you run each search separately, then apply RRF to their results in your client (server-side fusion is coming).

## When to use it

Reach for RRF whenever you combine results from separate searches and want each to contribute to the final ranking, most commonly full-text (BM25) with semantic (dense-vector). It's a robust default that works without normalizing scores or tuning per-signal weights.

## How it works

RRF scores each document by summing `1 / (k + rank)` across every ranking it appears in, where `rank` is the document's 1-based position in that ranking and `k` is a constant (the [original RRF paper](https://dl.acm.org/doi/10.1145/1571941.1572114) uses `k=60`). A document ranked highly in multiple searches accumulates the highest fused score. A document absent from a ranking gets nothing from it. Because only rank position matters, scores never need to be normalized.

```python Python theme={null}
def reciprocal_rank_fusion(rankings, k=60):
    """Fuse ranked lists of document IDs into one RRF-scored ranking.

    Each ranking is a list of `_id`s in rank order (best first).
    Returns a dict mapping `_id` to its fused score.
    """
    scores = {}
    for ranking in rankings:
        for rank, doc_id in enumerate(ranking, start=1):
            scores[doc_id] = scores.get(doc_id, 0.0) + 1.0 / (k + rank)
    return scores
```

## Combine two searches

This assumes an index whose [schema](/guides/search/full-text-search#schema-definition) declares an FTS-enabled `string` field (`body`) and a `dense_vector` field (`embedding`).

Run each search independently, pass the ranked `_id`s to `reciprocal_rank_fusion`, then sort by the fused score. Here, a full-text search and a semantic search over the same index are fused into one top-10 ranking:

```python Python theme={null}
import os
from pinecone import Pinecone

pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"])
index = pc.preview.index(name="docs-example")

query = "how do I reset my password?"
fetch_k = 50  # fetch deeper than the final top_k so weaker-but-present signals still count

# 1. Full-text (BM25) search.
text_hits = index.documents.search(
    namespace="__default__",
    top_k=fetch_k,
    score_by=[{"type": "text", "field": "body", "query": query}],
    include_fields=["*"],
).matches

# 2. Semantic (dense-vector) search. Embed the query with the same model as your documents.
query_embedding = pc.inference.embed(
    model="llama-text-embed-v2",
    inputs=[query],
    parameters={"input_type": "query"},
)
dense_hits = index.documents.search(
    namespace="__default__",
    top_k=fetch_k,
    score_by=[{"type": "dense_vector", "field": "embedding", "values": query_embedding[0]["values"]}],
    include_fields=["*"],
).matches

# 3. Fuse the two rankings client-side (reciprocal_rank_fusion is defined in "How it works" above).
fused = reciprocal_rank_fusion([
    [m._id for m in text_hits],
    [m._id for m in dense_hits],
])

# 4. Sort by fused score and keep the top results.
by_id = {m._id: m for m in text_hits}
for m in dense_hits:
    by_id.setdefault(m._id, m)

top_k = 10
for doc_id in sorted(fused, key=fused.get, reverse=True)[:top_k]:
    print(doc_id, fused[doc_id], getattr(by_id[doc_id], "body", ""))
```

## Tuning and extensions

* **`fetch_k`** (a variable in this example, not an API parameter) controls how deep each ranking is fetched before fusing. Raise it so a document that ranks well in one search but outside the top of the other still contributes. It should be at least your final `top_k`.
* **`k`** (default 60) controls how much a single ranking's top positions dominate the fused order. A larger `k` flattens the influence of any single top-ranked result.
* **Latency.** Run the searches in parallel (for example with `asyncio` or threads) so you pay the slowest search's latency, not the sum.
* **Weighting.** To favor one signal over another, weight each ranking's contribution (multiply its `1 / (k + rank)` terms by a per-ranking weight). It's a powerful relevance-tuning lever and can warrant its own guide; this page uses the unweighted default.

### Merge more than two rankings

RRF extends to any number of rankings. Pass more lists to `reciprocal_rank_fusion`; each additional search contributes another ranked list of `_id`s:

```python Python theme={null}
fused = reciprocal_rank_fusion([
    [m._id for m in text_hits],
    [m._id for m in dense_hits],
    [m._id for m in sparse_hits],  # e.g., a sparse-vector search
])
```


# Rerank results
Source: https://docs.pinecone.io/guides/search/rerank-results

Improve retrieval quality by reranking initial search results with a hosted or external model to surface the most relevant matches for RAG.

Reranking is used as part of a two-stage vector retrieval process to improve the quality of results. You first query an index for a given number of relevant results, and then you send the query and results to a reranking model. The reranking model scores the results based on their semantic relevance to the query and returns a new, more accurate ranking. This approach is one of the simplest methods for improving quality in retrieval augmented generation (RAG) pipelines.

Pinecone provides [hosted reranking models](#reranking-models) so it's easy to manage two-stage vector retrieval on a single platform. You can use a hosted model to rerank results as an integrated part of a query, or you can use a hosted model or external model to rerank results as a standalone operation.

<Note>
  To run through this guide in your browser, see the [Rerank example notebook](https://colab.research.google.com/github/pinecone-io/examples/blob/master/docs/pinecone-reranker.ipynb).
</Note>

## Integrated reranking

To rerank initial results as an integrated part of a query, without any extra steps, use the [`search`](/reference/api/latest/data-plane/search_records) operation with the `rerank` parameter, including the [hosted reranking model](#reranking-models) you want to use, the number of reranked results to return, and the fields to use for reranking, if different than the main query.

For example, the following code searches for the 3 records most semantically related to a query text and uses the `hosted bge-reranker-v2-m3` model to rerank the results and return only the 2 most relevant documents:

<CodeGroup>
  ```python Python theme={null}
  from pinecone import Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")

  # To get the unique host for an index, 
  # see https://docs.pinecone.io/guides/manage-data/target-an-index
  index = pc.Index(host="INDEX_HOST")

  ranked_results = index.search(
      namespace="example-namespace", 
      query={
          "inputs": {"text": "Disease prevention"}, 
          "top_k": 4
      },
      rerank={
          "model": "bge-reranker-v2-m3",
          "top_n": 2,
          "rank_fields": ["chunk_text"]
      },
      fields=["category", "chunk_text"]
  )

  print(ranked_results)
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone'

  const pc = new Pinecone({ apiKey: "YOUR_API_KEY" })

  // To get the unique host for an index, 
  // see https://docs.pinecone.io/guides/manage-data/target-an-index
  const namespace = pc.index("INDEX_NAME", "INDEX_HOST").namespace("example-namespace");

  const response = await namespace.searchRecords({
    query: {
      topK: 2,
      inputs: { text: 'Disease prevention' },
    },
    fields: ['chunk_text', 'category'],
    rerank: {
      model: 'bge-reranker-v2-m3',
      rankFields: ['chunk_text'],
      topN: 2,
    },
  });

  console.log(response);
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Index;
  import io.pinecone.configs.PineconeConfig;
  import io.pinecone.configs.PineconeConnection;
  import org.openapitools.db_data.client.ApiException;
  import org.openapitools.db_data.client.model.SearchRecordsRequestRerank;
  import org.openapitools.db_data.client.model.SearchRecordsResponse;

  import java.util.*;

  public class SearchText {
      public static void main(String[] args) throws ApiException {
          PineconeConfig config = new PineconeConfig("YOUR_API_KEY");
          // To get the unique host for an index, 
          // see https://docs.pinecone.io/guides/manage-data/target-an-index
          config.setHost("INDEX_HOST");
          PineconeConnection connection = new PineconeConnection(config);

          Index index = new Index(config, connection, "integrated-dense-java");

          String query = "Disease prevention";
          List<String> fields = new ArrayList<>();
          fields.add("category");
          fields.add("chunk_text");

          List<String>rankFields = new ArrayList<>();
          rankFields.add("chunk_text");
          SearchRecordsRequestRerank rerank = new SearchRecordsRequestRerank()
                  .query(query)
                  .model("bge-reranker-v2-m3")
                  .topN(2)
                  .rankFields(rankFields);

          SearchRecordsResponse recordsResponseReranked = index.searchRecordsByText(query,  "example-namespace", fields,4, null, rerank);

          System.out.println(recordsResponseReranked);
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "encoding/json"
      "fmt"
      "log"

      "github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func prettifyStruct(obj interface{}) string {
    	bytes, _ := json.MarshalIndent(obj, "", "  ")
      return string(bytes)
  }

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

      // To get the unique host for an index, 
      // see https://docs.pinecone.io/guides/manage-data/target-an-index
      idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST", Namespace: "example-namespace"})
      if err != nil {
          log.Fatalf("Failed to create IndexConnection for Host: %v", err)
      } 

      topN := int32(2)
      res, err := idxConnection.SearchRecords(ctx, &pinecone.SearchRecordsRequest{
          Query: pinecone.SearchRecordsQuery{
              TopK: 3,
              Inputs: &map[string]interface{}{
                  "text": "Disease prevention",
              },
          },
          Rerank: &pinecone.SearchRecordsRerank{
              Model:      "bge-reranker-v2-m3",
              TopN:       &topN,
              RankFields: []string{"chunk_text"},
          },
          Fields: &[]string{"chunk_text", "category"},
      })
      if err != nil {
          log.Fatalf("Failed to search records: %v", err)
      }
      fmt.Printf(prettifyStruct(res))
  }
  ```

  ```shell curl theme={null}
  INDEX_HOST="INDEX_HOST"
  NAMESPACE="YOUR_NAMESPACE"
  PINECONE_API_KEY="YOUR_API_KEY"

  curl "https://$INDEX_HOST/records/namespaces/$NAMESPACE/search" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: unstable" \
    -d '{
          "query": {
              "inputs": {"text": "Disease prevention"},
              "top_k": 4
          },
          "rerank": {
              "model": "bge-reranker-v2-m3",
              "top_n": 2,
              "rank_fields": ["chunk_text"]
          },
          "fields": ["category", "chunk_text"]
       }'
  ```
</CodeGroup>

The response looks as follows. For each hit, the `_score` represents the relevance of a document to the query, normalized between 0 and 1, with scores closer to 1 indicating higher relevance.

<CodeGroup>
  ```python Python theme={null}
  {'result': {'hits': [{'_id': 'rec3',
                        '_score': 0.004399413242936134,
                        'fields': {'category': 'immune system',
                                   'chunk_text': 'Rich in vitamin C and other '
                                                  'antioxidants, apples '
                                                  'contribute to immune health '
                                                  'and may reduce the risk of '
                                                  'chronic diseases.'}},
                       {'_id': 'rec4',
                        '_score': 0.0029235430993139744,
                        'fields': {'category': 'endocrine system',
                                   'chunk_text': 'The high fiber content in '
                                                  'apples can also help regulate '
                                                  'blood sugar levels, making '
                                                  'them a favorable snack for '
                                                  'people with diabetes.'}}]},
   'usage': {'embed_total_tokens': 8, 'read_units': 6, 'rerank_units': 1}}
  ```

  ```javascript JavaScript theme={null}
  {
    result: { 
      hits: [ 
        {
          _id: 'rec3',
          _score: 0.004399413242936134,
          fields: {
            category: 'immune system',
            chunk_text: 'Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases.'
          }
        },
        {
          _id: 'rec4',
          _score: 0.0029235430993139744,
          fields: {
            category: 'endocrine system',
            chunk_text: 'The high fiber content in apples can also help regulate blood sugar levels, making them a favorable snack for people with diabetes.'
          }
        }
      ]
    },
    usage: { 
      readUnits: 6, 
      embedTotalTokens: 8,
      rerankUnits: 1 
    }
  }
  ```

  ```java Java theme={null}
  class SearchRecordsResponse {
      result: class SearchRecordsResponseResult {
          hits: [class Hit {
              id: rec3
              score: 0.004399413242936134
              fields: {category=immune system, chunk_text=Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases.}
              additionalProperties: null
          }, class Hit {
              id: rec4
              score: 0.0029235430993139744
              fields: {category=endocrine system, chunk_text=The high fiber content in apples can also help regulate blood sugar levels, making them a favorable snack for people with diabetes.}
              additionalProperties: null
          }]
          additionalProperties: null
      }
      usage: class SearchUsage {
          readUnits: 6
          embedTotalTokens: 13
          rerankUnits: 1
          additionalProperties: null
      }
      additionalProperties: null
  }
  ```

  ```go Go theme={null}
  {
    "result": {
      "hits": [
        {
          "_id": "rec3",
          "_score": 0.13683891,
          "fields": {
            "category": "immune system",
            "chunk_text": "Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases."
          }
        },
        {
          "_id": "rec4",
          "_score": 0.0029235430993139744,
          "fields": {
            "category": "endocrine system",
            "chunk_text": "The high fiber content in apples can also help regulate blood sugar levels, making them a favorable snack for people with diabetes."
          }
        }
      ]
    },
    "usage": {
      "read_units": 6,
      "embed_total_tokens": 8,
      "rerank_units": 1
    }
  }
  ```

  ```json curl theme={null}
  {
      "result": {
          "hits": [
              {
                  "_id": "rec3",
                  "_score": 0.004433765076100826,
                  "fields": {
                      "category": "immune system",
                      "chunk_text": "Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases."
                  }
              },
              {
                  "_id": "rec4",
                  "_score": 0.0029121784027665854,
                  "fields": {
                      "category": "endocrine system",
                      "chunk_text": "The high fiber content in apples can also help regulate blood sugar levels, making them a favorable snack for people with diabetes."
                  }
              }
          ]
      },
      "usage": {
          "embed_total_tokens": 8,
          "read_units": 6,
          "rerank_units": 1
      }
  }
  ```
</CodeGroup>

## Standalone reranking

To rerank initial results as a standalone operation, use the [`rerank`](/reference/api/latest/inference/rerank) operation with the [hosted reranking model](#reranking-models) you want to use, the query results and the query, the number of ranked results to return, the field to use for reranking, and any other model-specific parameters.

For example, the following code uses the hosted `bge-reranker-v2-m3` model to rerank the values of the `documents.chunk_text` fields based on their relevance to the query and return only the 2 most relevant documents, along with their score:

<CodeGroup>
  ```python Python theme={null}
  from pinecone import Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")

  ranked_results = pc.inference.rerank(
      model="bge-reranker-v2-m3",
      query="What is AAPL's outlook, considering both product launches and market conditions?",
      documents=[
          {"id": "vec2", "chunk_text": "Analysts suggest that AAPL'\''s upcoming Q4 product launch event might solidify its position in the premium smartphone market."},
          {"id": "vec3", "chunk_text": "AAPL'\''s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production."},
          {"id": "vec1", "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones."},
      ],
      top_n=2,
      rank_fields=["chunk_text"],
      return_documents=True,
      parameters={
          "truncate": "END"
      }
  )

  print(ranked_results)
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone';

  const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' });

  const rerankingModel = 'bge-reranker-v2-m3';

  const query = "What is AAPL's outlook, considering both product launches and market conditions?";

  const documents = [
    { id: 'vec2', chunk_text: "Analysts suggest that AAPL's upcoming Q4 product launch event might solidify its position in the premium smartphone market." },
    { id: 'vec3', chunk_text: "AAPL's strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production." },
    { id: 'vec1', chunk_text: "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones." },
  ];

  const rerankOptions = {
    topN: 2,
    rankFields: ['chunk_text'],
    returnDocuments: true,
    parameters: {
      truncate: 'END'
    }, 
  };

  const rankedResults = await pc.inference.rerank(
    rerankingModel,
    query,
    documents,
    rerankOptions
  );

  console.log(rankedResults);
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Inference;
  import io.pinecone.clients.Pinecone;
  import org.openapitools.inference.client.model.RerankResult;
  import org.openapitools.inference.client.ApiException;

  import java.util.*;

  public class RerankExample {
      public static void main(String[] args) throws ApiException {
          Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build();
          Inference inference = pc.getInferenceClient();

          // The model to use for reranking
          String model = "bge-reranker-v2-m3";

          // The query to rerank documents against
          String query = "What is AAPL's outlook, considering both product launches and market conditions?";

          // Add the documents to rerank
          List<Map<String, Object>> documents = new ArrayList<>();
          Map<String, Object> doc1 = new HashMap<>();
          doc1.put("id", "vec2");
          doc1.put("chunk_text", "Analysts suggest that AAPL's upcoming Q4 product launch event might solidify its position in the premium smartphone market.");
          documents.add(doc1);

          Map<String, Object> doc2 = new HashMap<>();
          doc2.put("id", "vec3");
          doc2.put("chunk_text", "AAPL's strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production");
          documents.add(doc2);

          Map<String, Object> doc3 = new HashMap<>();
          doc3.put("id", "vec1");
          doc3.put("chunk_text", "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.");
          documents.add(doc3);

          // The fields to rank the documents by. If not provided, the default is "text"
          List<String> rankFields = Arrays.asList("chunk_text");

          // The number of results to return sorted by relevance. Defaults to the number of inputs
          int topN = 2;

          // Whether to return the documents in the response
          boolean returnDocuments = true;

          // Additional model-specific parameters for the reranker
          Map<String, Object> parameters = new HashMap<>();
          parameters.put("truncate", "END");

          // Send ranking request
          RerankResult result = inference.rerank(model, query, documents, rankFields, topN, returnDocuments, parameters);

          // Get ranked data
          System.out.println(result.getData());
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
  	"context"
  	"encoding/json"
  	"fmt"
  	"log"

  	"github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func prettifyStruct(obj interface{}) string {
  	bytes, _ := json.MarshalIndent(obj, "", "  ")
  	return string(bytes)
  }

  func main() {
  	ctx := context.Background()

  	pc, err := pinecone.NewClient(pinecone.NewClientParams{
  		ApiKey: "YOUR_API_KEY",
  	})
  	if err != nil {
  		log.Fatalf("Failed to create Client: %v", err)
  	}

  	rerankModel := "bge-reranker-v2-m3"
  	topN := 2
  	returnDocuments := true
  	documents := []pinecone.Document{
  		{"id": "vec2", "chunk_text": "Analysts suggest that AAPL's upcoming Q4 product launch event might solidify its position in the premium smartphone market."},
  		{"id": "vec3", "chunk_text": "AAPL's strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production."},
  		{"id": "vec1", "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones."},
  	}

  	ranking, err := pc.Inference.Rerank(ctx, &pinecone.RerankRequest{
  		Model:           rerankModel,
  		Query:           "What is AAPL's outlook, considering both product launches and market conditions?",
  		ReturnDocuments: &returnDocuments,
  		TopN:            &topN,
  		RankFields:      &[]string{"chunk_text"},
  		Documents:       documents,
  	})
  	if err != nil {
  		log.Fatalf("Failed to rerank: %v", err)
  	}
  	fmt.Printf(prettifyStruct(ranking))
  }
  ```

  ```shell curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"

  curl https://api.pinecone.io/rerank \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "X-Pinecone-Api-Version: 2025-10" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -d '{
    "model": "bge-reranker-v2-m3",
    "query": "What is AAPL'\''s outlook, considering both product launches and market conditions?",
    "documents": [
      {"id": "vec2", "chunk_text": "Analysts suggest that AAPL'\''s upcoming Q4 product launch event might solidify its position in the premium smartphone market."},
      {"id": "vec3", "chunk_text": "AAPL'\''s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production."},
      {"id": "vec1", "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones."}
    ],
    "top_n": 2,
    "rank_fields": ["chunk_text"],
    "return_documents": true,
    "parameters": {
      "truncate": "END"
    }
  }'
  ```
</CodeGroup>

The response looks as follows. For each hit, the \_score represents the relevance of a document to the query, normalized between 0 and 1, with scores closer to 1 indicating higher relevance.

<CodeGroup>
  ```python Python theme={null}
  RerankResult(
    model='bge-reranker-v2-m3',
    data=[{
      index=0,
      score=0.004166256,
      document={
          id='vec2',
          chunk_text="Analysts suggest that AAPL'''s upcoming Q4 product launch event might solidify its position in the premium smartphone market."
      }
    },{
      index=2,
      score=0.0011513996,
      document={
          id='vec1',
          chunk_text='AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.'
      }
    }],
    usage={'rerank_units': 1}
  )
  ```

  ```javascript JavaScript theme={null}
  {
    model: 'bge-reranker-v2-m3',
    data: [
      { index: 0, score: 0.004166256, document: [id: 'vec2', chunk_text: "Analysts suggest that AAPL'''s upcoming Q4 product launch event might solidify its position in the premium smartphone market."] },
      { index: 2, score: 0.0011513996, document: [id: 'vec1', chunk_text: 'AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.'] }
    ],
    usage: { rerankUnits: 1 }
  }
  ```

  ```java Java theme={null}
  [class RankedDocument {
      index: 0
      score: 0.0063143647
      document: {id=vec2, chunk_text=Analysts suggest that AAPL's upcoming Q4 product launch event might solidify its position in the premium smartphone market.}
      additionalProperties: null
  }, class RankedDocument {
      index: 2
      score: 0.0011513996
      document: {id=vec1, chunk_text=AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.}
      additionalProperties: null
  }]
  ```

  ```go Go theme={null}
  {
    "data": [
      {
        "document": {
          "id": "vec2",
          "chunk_text": "Analysts suggest that AAPL's upcoming Q4 product launch event might solidify its position in the premium smartphone market."
        },
        "index": 0,
        "score": 0.0063143647
      },
      {
        "document": {
          "id": "vec1",
          "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones."
        },
        "index": 2,
        "score": 0.0011513996
      }
    ],
    "model": "bge-reranker-v2-m3",
    "usage": {
      "rerank_units": 1
    }
  }
  ```

  ```json curl theme={null}
  {
      "model": "bge-reranker-v2-m3",
      "data": [
          {
              "index": 0,
              "document": {
                  "chunk_text": "Analysts suggest that AAPL's upcoming Q4 product launch event might solidify its position in the premium smartphone market.",
                  "id": "vec2"
              },
              "score": 0.007606672
          },
          {
              "index": 3,
              "document": {
                  "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.",
                  "id": "vec1"
              },
              "score": 0.0013406205
          }
      ],
      "usage": {
          "rerank_units": 1
      }
  }
  ```
</CodeGroup>

## Rerank results on the default field

To [rerank search results](/reference/api/latest/inference/rerank), specify a [supported reranking model](/guides/search/rerank-results#reranking-models), and provide documents and a query as well as other model-specific parameters. By default, Pinecone expects the documents to be in the `documents.text` field.

For example, the following request uses the `bge-reranker-v2-m3` reranking model to rerank the values of the `documents.text` field based on their relevance to the query, `"The tech company Apple is known for its innovative products like the iPhone."`.

<Note>
  With `truncate` set to `"END"`, the input sequence (`query` + `document`) is truncated at the token limit (`1024`); to return an error instead, you'd set `truncate` to `"NONE"` or leave the parameter out.
</Note>

<CodeGroup>
  ```python Python theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")

  result = pc.inference.rerank(
      model="bge-reranker-v2-m3",
      query="The tech company Apple is known for its innovative products like the iPhone.",
      documents=[
          {"id": "vec1", "text": "Apple is a popular fruit known for its sweetness and crisp texture."},
          {"id": "vec2", "text": "Many people enjoy eating apples as a healthy snack."},
          {"id": "vec3", "text": "Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces."},
          {"id": "vec4", "text": "An apple a day keeps the doctor away, as the saying goes."},
      ],
      top_n=4,
      return_documents=True,
      parameters={
          "truncate": "END"
      }
  )

  print(result)
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone';

  const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' });

  const rerankingModel = 'bge-reranker-v2-m3';

  const query = 'The tech company Apple is known for its innovative products like the iPhone.';

  const documents = [
    { id: 'vec1', text: 'Apple is a popular fruit known for its sweetness and crisp texture.' },
    { id: 'vec2', text: 'Many people enjoy eating apples as a healthy snack.' },
    { id: 'vec3', text: 'Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces.' },
    { id: 'vec4', text: 'An apple a day keeps the doctor away, as the saying goes.' },
  ];

  const rerankOptions = {
    topN: 4,
    returnDocuments: true,
    parameters: {
      truncate: 'END'
    }, 
  };

  const response = await pc.inference.rerank(
    rerankingModel,
    query,
    documents,
    rerankOptions
  );

  console.log(response);
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Inference;
  import io.pinecone.clients.Pinecone;
  import org.openapitools.inference.client.model.RerankResult;
  import org.openapitools.inference.client.ApiException;

  import java.util.*;

  public class RerankExample {
      public static void main(String[] args) throws ApiException {
          Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build();
          Inference inference = pc.getInferenceClient();

          // The model to use for reranking
          String model = "bge-reranker-v2-m3";

          // The query to rerank documents against
          String query = "The tech company Apple is known for its innovative products like the iPhone.";

          // Add the documents to rerank
          List<Map<String, Object>> documents = new ArrayList<>();
          Map<String, Object> doc1 = new HashMap<>();
          doc1.put("id", "vec1");
          doc1.put("text", "Apple is a popular fruit known for its sweetness and crisp texture.");
          documents.add(doc1);

          Map<String, Object> doc2 = new HashMap<>();
          doc2.put("id", "vec2");
          doc2.put("text", "Many people enjoy eating apples as a healthy snack.");
          documents.add(doc2);

          Map<String, Object> doc3 = new HashMap<>();
          doc3.put("id", "vec3");
          doc3.put("text", "Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces.");
          documents.add(doc3);

          Map<String, Object> doc4 = new HashMap<>();
          doc4.put("id", "vec4");
          doc4.put("text", "An apple a day keeps the doctor away, as the saying goes.");
          documents.add(doc4);

          // The fields to rank the documents by. If not provided, the default is "text"
          List<String> rankFields = Arrays.asList("text");

          // The number of results to return sorted by relevance. Defaults to the number of inputs
          int topN = 4;

          // Whether to return the documents in the response
          boolean returnDocuments = true;

          // Additional model-specific parameters for the reranker
          Map<String, Object> parameters = new HashMap<>();
          parameters.put("truncate", "END");

          // Send ranking request
          RerankResult result = inference.rerank(model, query, documents, rankFields, topN, returnDocuments, parameters);

          // Get ranked data
          System.out.println(result.getData());
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "fmt"
      "log"

      "github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

      rerankModel := "bge-reranker-v2-m3"
      topN := 4
      returnDocuments := true
      documents := []pinecone.Document{
          {"id": "vec1", "text": "Apple is a popular fruit known for its sweetness and crisp texture."},
          {"id": "vec2", "text": "Many people enjoy eating apples as a healthy snack."},
          {"id": "vec3", "text": "Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces."},
          {"id": "vec4", "text": "An apple a day keeps the doctor away, as the saying goes."},
      }

      ranking, err := pc.Inference.Rerank(ctx, &pinecone.RerankRequest{
          Model:           rerankModel,
          Query:           "The tech company Apple is known for its innovative products like the iPhone.",
          ReturnDocuments: &returnDocuments,
          TopN:            &topN,
          RankFields:      &[]string{"text"},
          Documents:       documents,
      })
      if err != nil {
          log.Fatalf("Failed to rerank: %v", err)
      }
      fmt.Printf("Rerank result: %+v\n", ranking)
  }
  ```

  ```shell curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"

  curl https://api.pinecone.io/rerank \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "X-Pinecone-Api-Version: 2025-10" \
    -H "Api-Key: $PINECONE_API_KEY" \
  -d '{
    "model": "bge-reranker-v2-m3",
    "query": "The tech company Apple is known for its innovative products like the iPhone.",
    "return_documents": true,
    "top_n": 4,
    "documents": [
      {"id": "vec1", "text": "Apple is a popular fruit known for its sweetness and crisp texture."},
      {"id": "vec2", "text": "Many people enjoy eating apples as a healthy snack."},
      {"id": "vec3", "text": "Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces."},
      {"id": "vec4", "text": "An apple a day keeps the doctor away, as the saying goes."}
    ],
    "parameters": {
      "truncate": "END"
    }
  }'
  ```
</CodeGroup>

The returned object contains documents with relevance scores:

<Note>
  Normalized between 0 and 1, the `score` represents the relevance of a passage to the query, with scores closer to 1 indicating higher relevance.
</Note>

<CodeGroup>
  ```python Python theme={null}
  RerankResult(
    model='bge-reranker-v2-m3',
    data=[
      { index=2, score=0.48357219,
        document={id="vec3", text="Apple Inc. has re..."} },
      { index=0, score=0.048405956,
        document={id="vec1", text="Apple is a popula..."} },
      { index=3, score=0.007846239,
        document={id="vec4", text="An apple a day ke..."} },
      { index=1, score=0.0006563728,
        document={id="vec2", text="Many people enjoy..."} }
    ],
    usage={'rerank_units': 1}
  )
  ```

  ```javascript JavaScript theme={null}
  {
    model: 'bge-reranker-v2-m3',
    data: [
      { index: 2, score: 0.48357219, document: [Object] },
      { index: 0, score: 0.048405956, document: [Object] },
      { index: 3, score: 0.007846239, document: [Object] },
      { index: 1, score: 0.0006563728, document: [Object] }
    ],
    usage: { rerankUnits: 1 }
  }
  ```

  ```java Java theme={null}
  [class RankedDocument {
      index: 2
      score: 0.48357219
      document: {id=vec3, text=Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces.}
      additionalProperties: null
  }, class RankedDocument {
      index: 0
      score: 0.048405956
      document: {id=vec1, text=Apple is a popular fruit known for its sweetness and crisp texture.}
      additionalProperties: null
  }, class RankedDocument {
      index: 3
      score: 0.007846239
      document: {id=vec4, text=An apple a day keeps the doctor away, as the saying goes.}
      additionalProperties: null
  }, class RankedDocument {
      index: 1
      score: 0.0006563728
      document: {id=vec2, text=Many people enjoy eating apples as a healthy snack.}
      additionalProperties: null
  }]
  ```

  ```go Go theme={null}
  Rerank result: {
    "data": [
      {
        "document": {
          "id": "vec3",
          "text": "Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces."
        },
        "index": 2,
        "score": 0.48357219
      },
      {
        "document": {
          "id": "vec1",
          "text": "Apple is a popular fruit known for its sweetness and crisp texture."
        },
        "index": 0,
        "score": 0.048405956
      },
      {
        "document": {
          "id": "vec4",
          "text": "An apple a day keeps the doctor away, as the saying goes."
        },
        "index": 3,
        "score": 0.007846239
      },
      {
        "document": {
          "id": "vec2",
          "text": "Many people enjoy eating apples as a healthy snack."
        },
        "index": 1,
        "score": 0.0006563728
      }
    ],
    "model": "bge-reranker-v2-m3",
    "usage": {
      "rerank_units": 1
    }
  }
  ```

  ```JSON curl theme={null}
  {
    "data":[
      {
        "index":2,
        "document":{
          "id":"vec3",
          "text":"Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces."
        },
        "score":0.47654688
      },
      {
        "index":0,
        "document":{
          "id":"vec1",
          "text":"Apple is a popular fruit known for its sweetness and crisp texture."
        },
        "score":0.047963805
      },
      {
        "index":3,
        "document":{
          "id":"vec4",
          "text":"An apple a day keeps the doctor away, as the saying goes."
        },
        "score":0.007587992
      },
      {
        "index":1,
        "document":{
          "id":"vec2",
          "text":"Many people enjoy eating apples as a healthy snack."
        },
        "score":0.0006491712
      }
    ],
    "usage":{
      "rerank_units":1
    }
  }
  ```
</CodeGroup>

## Rerank results on a custom field

To [rerank results](/reference/api/latest/inference/rerank) on a field other than `documents.text`, provide the `rank_fields` parameter to specify the fields on which to rerank.

<Note>
  The [`bge-reranker-v2-m3`](#bge-reranker-v2-m3) and [`pinecone-rerank-v0`](#pinecone-rerank-v0) models support only a single rerank field. [`cohere-rerank-4-fast`](#cohere-rerank-4-fast) and [`cohere-rerank-3.5`](#cohere-rerank-3-5) support multiple rerank fields, ranked based on the order of the fields specified.
</Note>

For example, the following request reranks documents based on the values of the `documents.my_field` field:

<CodeGroup>
  ```python Python theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")

  result = pc.inference.rerank(
      model="bge-reranker-v2-m3",
      query="The tech company Apple is known for its innovative products like the iPhone.",
      documents=[
          {"id": "vec1", "my_field": "Apple is a popular fruit known for its sweetness and crisp texture."},
          {"id": "vec2", "my_field": "Many people enjoy eating apples as a healthy snack."},
          {"id": "vec3", "my_field": "Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces."},
          {"id": "vec4", "my_field": "An apple a day keeps the doctor away, as the saying goes."},
      ],
      rank_fields=["my_field"],
      top_n=4,
      return_documents=True,
      parameters={
          "truncate": "END"
      }
  )
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone';

  const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' });

  const rerankingModel = 'bge-reranker-v2-m3';

  const query = 'The tech company Apple is known for its innovative products like the iPhone.';

  const documents = [
    { id: 'vec1', my_field: 'Apple is a popular fruit known for its sweetness and crisp texture.' },
    { id: 'vec2', my_field: 'Many people enjoy eating apples as a healthy snack.' },
    { id: 'vec3', my_field: 'Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces.' },
    { id: 'vec4', my_field: 'An apple a day keeps the doctor away, as the saying goes.' },
  ];

  const rerankOptions = {
    rankFields: ['my_field'],
    topN: 4,
    returnDocuments: true,
    parameters: {
      truncate: "END"
    }, 
  };

  const response = await pc.inference.rerank(
    rerankingModel,
    query,
    documents,
    rerankOptions
  );

  console.log(response);
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Inference;
  import io.pinecone.clients.Pinecone;
  import org.openapitools.inference.client.model.RerankResult;
  import org.openapitools.inference.client.ApiException;

  import java.util.*;

  public class RerankExample {
      public static void main(String[] args) throws ApiException {
          Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build();
          Inference inference = pc.getInferenceClient();

          // The model to use for reranking
          String model = "bge-reranker-v2-m3";

          // The query to rerank documents against
          String query = "The tech company Apple is known for its innovative products like the iPhone.";

          // Add the documents to rerank
          List<Map<String, String>> documents = new ArrayList<>();
          Map<String, String> doc1 = new HashMap<>();
          doc1.put("id", "vec1");
          doc1.put("my_field", "Apple is a popular fruit known for its sweetness and crisp texture.");
          documents.add(doc1);

          Map<String, String> doc2 = new HashMap<>();
          doc2.put("id", "vec2");
          doc2.put("my_field", "Many people enjoy eating apples as a healthy snack.");
          documents.add(doc2);

          Map<String, String> doc3 = new HashMap<>();
          doc3.put("id", "vec3");
          doc3.put("my_field", "Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces.");
          documents.add(doc3);

          Map<String, String> doc4 = new HashMap<>();
          doc4.put("id", "vec4");
          doc4.put("my_field", "An apple a day keeps the doctor away, as the saying goes.");
          documents.add(doc4);

          // The fields to rank the documents by. If not provided, the default is "text"
          List<String> rankFields = Arrays.asList("my_field");

          // The number of results to return sorted by relevance. Defaults to the number of inputs
          int topN = 2;

          // Whether to return the documents in the response
          boolean returnDocuments = true;

          // Additional model-specific parameters for the reranker
          Map<String, String> parameters = new HashMap<>();
          parameters.put("truncate", "END");

          // Send ranking request
          RerankResult result = inference.rerank(model, query, documents, rankFields, topN, returnDocuments, parameters);

          // Get ranked data
          System.out.println(result.getData());
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "fmt"
      "log"

      "github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

      rerankModel := "bge-reranker-v2-m3"
      topN := 4
      returnDocuments := true
      documents := []pinecone.Document{
          {"id": "vec1", "my_field": "Apple is a popular fruit known for its sweetness and crisp texture."},
          {"id": "vec2", "my_field": "Many people enjoy eating apples as a healthy snack."},
          {"id": "vec3", "my_field": "Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces."},
          {"id": "vec4", "my_field": "An apple a day keeps the doctor away, as the saying goes."},
      }

      ranking, err := pc.Inference.Rerank(ctx, &pinecone.RerankRequest{
          Model:           rerankModel,
          Query:           "The tech company Apple is known for its innovative products like the iPhone.",
          ReturnDocuments: &returnDocuments,
          TopN:            &topN,
          RankFields:      &[]string{"my_field"},
          Documents:       documents,
      })
      if err != nil {
          log.Fatalf("Failed to rerank: %v", err)
      }
      fmt.Printf("Rerank result: %+v\n", ranking)
  }
  ```

  ```shell curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"

  curl "https://api.pinecone.io/rerank" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
    -H "X-Pinecone-Api-Version: 2025-10" \
    -H "Api-Key: $PINECONE_API_KEY" \
  -d '{
    "model": "bge-reranker-v2-m3",
    "query": "The tech company Apple is known for its innovative products like the iPhone.",
    "return_documents": true,
    "top_n": 4,
    "rank_fields": ["my_field"],
    "documents": [
      {"id": "vec1", "my_field": "Apple is a popular fruit known for its sweetness and crisp texture."},
      {"id": "vec2", "my_field": "Many people enjoy eating apples as a healthy snack."},
      {"id": "vec3", "my_field": "Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces."},
      {"id": "vec4", "my_field": "An apple a day keeps the doctor away, as the saying goes."}
    ],
    "parameters": {
      "truncate": "END"
    }
  }'
  ```
</CodeGroup>

## Reranking models

Pinecone hosts several reranking models so it's easy to manage two-stage vector retrieval on a single platform. You can use a hosted model to rerank results as an integrated part of a query, or you can use a hosted model to rerank results as a standalone operation.

The following reranking models are hosted by Pinecone.

<Note>
  To understand how cost is calculated for reranking, see [Reranking cost](/guides/manage-cost/understanding-cost#reranking). To get model details via the API, see [List models](/reference/api/latest/inference/list_models) and [Describe a model](/reference/api/latest/inference/describe_model).
</Note>

<AccordionGroup>
  <Accordion title="cohere-rerank-4-fast">
    <PaidOnly />

    [`cohere-rerank-4-fast`](/models/cohere-rerank-4-fast) is Cohere's latest reranking model (Cohere Rerank 4.0 Fast), improving relevance quality for a wide range of enterprise search applications. Cohere Rerank 4.0 is hosted on Azure AI under the Global Standard deployment type, and requests may be processed in regions outside the United States.

    **Details**

    * Modality: Text
    * Max tokens per document: 8,192
    * Max documents: 250

    The relevance scores produced by `cohere-rerank-4-fast` are not directly comparable to those from `cohere-rerank-3.5`. This does not affect sorting, but any application logic that uses a fixed score threshold to make decisions must be re-calibrated for the new model.

    For rate limits, see [Rerank requests per minute](/reference/api/database-limits#rerank-requests-per-minute-per-model) and [Rerank requests per month](/reference/api/database-limits#rerank-requests-per-month-per-model).

    **Parameters**

    The `cohere-rerank-4-fast` model supports the following parameters:

    | Parameter            | Type             | Required/Optional | Description                                                                        | Default    |
    | :------------------- | :--------------- | :---------------- | :--------------------------------------------------------------------------------- | :--------- |
    | `max_tokens_per_doc` | integer          | Optional          | Documents longer than this are truncated. Max `4096`.                              | `1024`     |
    | `rank_fields`        | array of strings | Optional          | The fields to use for reranking, in priority order (e.g., `["field1", "field2"]`). | `["text"]` |
  </Accordion>

  <Accordion title="cohere-rerank-3.5">
    <PaidOnly />

    <Note>
      `cohere-rerank-3.5` is deprecated as of July 1, 2026. Starting August 1, 2026, requests to `cohere-rerank-3.5` are automatically served by [`cohere-rerank-4-fast`](#cohere-rerank-4-fast). Migrate your rerank requests to `cohere-rerank-4-fast` before then to control the transition yourself. Because `cohere-rerank-4-fast` returns different relevance scores, re-tune any hard-coded score thresholds before the transition.
    </Note>

    [`cohere-rerank-3.5`](/models/cohere-rerank-3.5) is Cohere's previous-generation reranking model, balancing performance and latency for a wide range of enterprise search applications.

    **Details**

    * Modality: Text
    * Max tokens per query and document pair: 40,000
    * Max documents: 200

    For rate limits, see [Rerank requests per minute](/reference/api/database-limits#rerank-requests-per-minute-per-model) and [Rerank request per month](/reference/api/database-limits#rerank-requests-per-month-per-model).

    **Parameters**

    The `cohere-rerank-3.5` model supports the following parameters:

    | Parameter            | Type             | Required/Optional | Description                                                                                                                             |            |
    | :------------------- | :--------------- | :---------------- | :-------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
    | `max_chunks_per_doc` | integer          | Optional          | Long documents will be automatically truncated to the specified number of chunks. Accepted range: `1 - 3072`.                           |            |
    | `rank_fields`        | array of strings | Optional          | The fields to use for reranking. The model reranks based on the order of the fields specified (e.g., `["field1", "field2", "field3"]`). | `["text"]` |
  </Accordion>

  <Accordion title="bge-reranker-v2-m3">
    [`bge-reranker-v2-m3`](/models/bge-reranker-v2-m3) is a high-performance, multilingual reranking model that works well on messy data and short queries expected to return medium-length passages of text (1-2 paragraphs).

    **Details**

    * Modality: Text
    * Max tokens per query and document pair: 1024
    * Max documents: 100

    For rate limits, see [Rerank requests per minute](/reference/api/database-limits#rerank-requests-per-minute-per-model) and [Rerank request per month](/reference/api/database-limits#rerank-requests-per-month-per-model).

    **Parameters**

    The `bge-reranker-v2-m3` model supports the following parameters:

    | Parameter     | Type             | Required/Optional | Description                                                                                                                                                                                                                                    | Default    |
    | :------------ | :--------------- | :---------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------- |
    | `truncate`    | string           | Optional          | How to handle inputs longer than those supported by the model. Accepted values: `END` or `NONE`.<br /><br />`END` truncates the input sequence at the input token limit. `NONE` returns an error when the input exceeds the input token limit. | `NONE`     |
    | `rank_fields` | array of strings | Optional          | The field to use for reranking. The model supports only a single rerank field.                                                                                                                                                                 | `["text"]` |
  </Accordion>

  <Accordion title="pinecone-rerank-v0">
    <PP />

    [`pinecone-rerank-v0`](/models/pinecone-rerank-v0) is a state of the art reranking model that out-performs competitors on widely accepted benchmarks. It can handle chunks up to 512 tokens (1-2 paragraphs).

    **Details**

    * Modality: Text
    * Max tokens per query and document pair: 512
    * Max documents: 100

    For rate limits, see [Rerank requests per minute](/reference/api/database-limits#rerank-requests-per-minute-per-model) and [Rerank request per month](/reference/api/database-limits#rerank-requests-per-month-per-model).

    **Parameters**

    The `pinecone-rerank-v0` model supports the following parameters:

    | Parameter     | Type             | Required/Optional | Description                                                                                                                                                                                                                                    | Default    |
    | :------------ | :--------------- | :---------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------- |
    | `truncate`    | string           | Optional          | How to handle inputs longer than those supported by the model. Accepted values: `END` or `NONE`.<br /><br />`END` truncates the input sequence at the input token limit. `NONE` returns an error when the input exceeds the input token limit. | `END`      |
    | `rank_fields` | array of strings | Optional          | The field to use for reranking. The model supports only a single rerank field.                                                                                                                                                                 | `["text"]` |
  </Accordion>
</AccordionGroup>


# Search overview
Source: https://docs.pinecone.io/guides/search/search-overview

Compare Pinecone search types and choose the right retrieval approach: full-text (BM25), semantic (dense vector), sparse lexical, and hybrid.

<Tip>
  Searches consume [read units (RUs)](/guides/manage-cost/understanding-cost#read-units). See [Understanding cost](/guides/manage-cost/understanding-cost#query) for how query cost is calculated.
</Tip>

## Search types

* [Full-text search](/guides/search/full-text-search)
* [Semantic search](/guides/search/semantic-search) (dense-vector)
* [Sparse-vector search (also called sparse-vector lexical search)](/guides/search/lexical-search)
* [Hybrid search](/guides/search/hybrid-search)

## Choosing a search approach

Pinecone supports four retrieval approaches. They differ in the signal they rank on and the index shape they require.

### Quick decision tree

Walk through these questions in order — pick the first match.

1. **Do your queries share specific tokens with the data?** (Product names, error messages, source code, named entities, technical jargon, identifiers.) → **[Full-text search](/guides/search/full-text-search)**. BM25 ranks results that share tokens with the query; Lucene syntax adds boolean and phrase operators.

2. **Are your queries natural language where meaning matters more than exact wording?** (Synonyms, paraphrases, conceptual similarity.) → **[Semantic search](/guides/search/semantic-search)** with a dense vector field.

3. **Do you produce a learned sparse-vector representation upstream of Pinecone?** (For example, using [`pinecone-sparse-english-v0`](/models/pinecone-sparse-english-v0) or your own sparse encoder.) → **[Sparse-vector lexical search](/guides/search/lexical-search)**.

4. **Do you need both semantic and keyword signals on the same data?**
   * **On a JSON-document workload** → **[Full-text search](/guides/search/full-text-search)** with a multi-field schema. Declare a `dense_vector` field alongside one or more FTS-enabled `string` fields. A single search request ranks by one signal; combine them by adding a text-match filter to a `dense_vector` query, or by running two searches and merging results client-side.
   * **On a vector-only records workload** → **[Hybrid search](/guides/search/hybrid-search)**. Store a dense vector and a sparse vector on each record in a single index (vector API).

### Approach details

A useful gradient: **dense** ranks on concept (semantic similarity), **full-text search** ranks on strict character-level token matching (BM25), and **sparse-vector lexical search** sits between them — token-aware, but with learned per-token weights and term expansion.

* **[Full-text search](/guides/search/full-text-search)** — **recommended** for keyword and phrase search over text content. You upsert typed JSON documents and rank with `score_by`: BM25 token matching on an FTS-enabled `string` field, Lucene query syntax (`query_string`), `dense_vector` similarity, or `sparse_vector` similarity. A single index with a document schema can mix all four field types, so it's also the recommended single-index path when a workload needs more than one signal (BM25 + dense, BM25 + sparse, etc.).

* **[Semantic search](/guides/search/semantic-search) (dense-vector)** — for queries where intent and meaning matter more than exact keyword matches (synonyms, paraphrases, conceptual similarity). Uses dense embeddings.

* **[Sparse-vector search (also called sparse-vector lexical search)](/guides/search/lexical-search)** — recommended for workflows that use a learned sparse-vector model (for example, [`pinecone-sparse-english-v0`](/models/pinecone-sparse-english-v0)) or where the application owns the sparse-vector representation directly. For general-purpose keyword and phrase retrieval over text, start with full-text search.

* **[Hybrid search](/guides/search/hybrid-search)** — combines dense and sparse vectors in a single index (vector API) for vector-centric workflows that need both semantic and lexical signals. For document-centric workflows that combine keyword matching with vector ranking, the most common pattern is dense (or sparse) ranking restricted by a text-match filter on an FTS-enabled `string` field — for example, semantic search across a corpus narrowed to documents containing an exact phrase. To weight BM25 and dense rankings against each other, run separate searches and merge the results client-side.

Once you've chosen an approach, see [Data modeling](/guides/index-data/data-modeling) to structure your documents or records, then [Create an index](/guides/index-data/create-an-index) to set it up.

## Optimization

* [Filter by metadata](/guides/search/filter-by-metadata)
* [Rerank results](/guides/search/rerank-results)
* [Parallel queries](/guides/search/semantic-search#parallel-queries)

## Limits

| Metric            | Limit  |
| :---------------- | :----- |
| Max `top_k` value | 10,000 |
| Max result size   | 4MB    |

The query result size is affected by the dimension of the dense vectors and whether or not dense vector values and metadata are included in the result.

<Tip>
  If a query fails due to exceeding the 4MB result size limit, choose a lower `top_k` value, or use `include_metadata=False` or `include_values=False` to exclude metadata or values from the result. For better performance, especially with higher `top_k` values, avoid including vector values unless you need them.
</Tip>

## Cost

* To understand how cost is calculated for queries, see [Understanding cost](/guides/manage-cost/understanding-cost#query).
* For up-to-date pricing information, see [Pricing](https://www.pinecone.io/pricing/).

## Data freshness

Pinecone is eventually consistent, so there can be a slight delay before new or changed records are visible to queries. You can view index stats to [check data freshness](/guides/index-data/check-data-freshness).


# Semantic search
Source: https://docs.pinecone.io/guides/search/semantic-search

Search a Pinecone index of dense vectors to find semantically similar records using text or vector queries, top_k results, and nearest neighbor lookup.

This page shows you how to search an [index of dense vectors](/guides/index-data/indexing-overview#indexes-with-dense-vectors) for records that are most similar in meaning and context to a query. This is often called semantic search, nearest neighbor search, similarity search, or just vector search.

Semantic search uses [dense vectors](https://www.pinecone.io/learn/vector-embeddings/). Each number in a dense vector corresponds to a point in a multidimensional space. Vectors that are closer together in that space are semantically similar.

## Search with text

<Note>
  Searching with text is supported only for [indexes with integrated embedding](/guides/index-data/indexing-overview#integrated-embedding).
</Note>

To search an index of dense vectors with a query text, use the [`search_records`](/reference/api/latest/data-plane/search_records) operation with the following parameters:

* The `namespace` to query. To use the default namespace, set the namespace to `"__default__"`.
* The `query.inputs.text` parameter with the query text. Pinecone uses the embedding model integrated with the index to convert the text to a dense vector automatically.
* The `query.top_k` parameter with the number of similar records to return.
* Optionally, you can specify the `fields` to return in the response. If not specified, the response will include all fields.

For example, the following code searches for the 2 records most semantically related to a query text:

<CodeGroup>
  ```python Python theme={null}
  from pinecone import Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")

  # To get the unique host for an index, 
  # see https://docs.pinecone.io/guides/manage-data/target-an-index
  index = pc.Index(host="INDEX_HOST")

  results = index.search(
      namespace="example-namespace", 
      query={
          "inputs": {"text": "Disease prevention"}, 
          "top_k": 2
      },
      fields=["category", "chunk_text"]
  )

  print(results)
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone'

  const pc = new Pinecone({ apiKey: "YOUR_API_KEY" })

  // To get the unique host for an index, 
  // see https://docs.pinecone.io/guides/manage-data/target-an-index
  const namespace = pc.index("INDEX_NAME", "INDEX_HOST").namespace("example-namespace");

  const response = await namespace.searchRecords({
    query: {
      topK: 2,
      inputs: { text: 'Disease prevention' },
    },
    fields: ['chunk_text', 'category'],
  });

  console.log(response);
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Index;
  import io.pinecone.configs.PineconeConfig;
  import io.pinecone.configs.PineconeConnection;
  import org.openapitools.db_data.client.ApiException;
  import org.openapitools.db_data.client.model.SearchRecordsResponse;

  import java.util.*;

  public class SearchText {
      public static void main(String[] args) throws ApiException {
          PineconeConfig config = new PineconeConfig("YOUR_API_KEY");
          // To get the unique host for an index, 
          // see https://docs.pinecone.io/guides/manage-data/target-an-index
          config.setHost("INDEX_HOST");
          PineconeConnection connection = new PineconeConnection(config);

          Index index = new Index(config, connection, "integrated-dense-java");

          String query = "Disease prevention";
          List<String> fields = new ArrayList<>();
          fields.add("category");
          fields.add("chunk_text");

          // Search the index
          SearchRecordsResponse recordsResponse = index.searchRecordsByText(query,  "example-namespace", fields, 2, null, null);

          // Print the results
          System.out.println(recordsResponse);
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "encoding/json"
      "fmt"
      "log"

      "github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func prettifyStruct(obj interface{}) string {
    	bytes, _ := json.MarshalIndent(obj, "", "  ")
      return string(bytes)
  }

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

      // To get the unique host for an index, 
      // see https://docs.pinecone.io/guides/manage-data/target-an-index
      idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST", Namespace: "example-namespace"})
      if err != nil {
          log.Fatalf("Failed to create IndexConnection for Host: %v", err)
      } 

      res, err := idxConnection.SearchRecords(ctx, &pinecone.SearchRecordsRequest{
          Query: pinecone.SearchRecordsQuery{
              TopK: 2,
              Inputs: &map[string]interface{}{
                  "text": "Disease prevention",
              },
          },
          Fields: &[]string{"chunk_text", "category"},
      })
      if err != nil {
          log.Fatalf("Failed to search records: %v", err)
      }
      fmt.Printf(prettifyStruct(res))
  }
  ```

  ```shell curl theme={null}
  INDEX_HOST="INDEX_HOST"
  NAMESPACE="YOUR_NAMESPACE"
  PINECONE_API_KEY="YOUR_API_KEY"

  curl "https://$INDEX_HOST/records/namespaces/$NAMESPACE/search" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: unstable" \
    -d '{
          "query": {
              "inputs": {"text": "Disease prevention"},
              "top_k": 2
          },
          "fields": ["category", "chunk_text"]
       }'
  ```
</CodeGroup>

The response will look as follows. Each record is returned with a similarity score that represents its distance to the query vector, calculated according to the [similarity metric](/guides/index-data/create-an-index#similarity-metrics) for the index.

<CodeGroup>
  ```python Python theme={null}
  {'result': {'hits': [{'_id': 'rec3',
                        '_score': 0.8204272389411926,
                        'fields': {'category': 'immune system',
                                   'chunk_text': 'Rich in vitamin C and other '
                                                 'antioxidants, apples '
                                                 'contribute to immune health '
                                                 'and may reduce the risk of '
                                                 'chronic diseases.'}},
                       {'_id': 'rec1',
                        '_score': 0.7931625843048096,
                        'fields': {'category': 'digestive system',
                                   'chunk_text': 'Apples are a great source of '
                                                 'dietary fiber, which supports '
                                                 'digestion and helps maintain a '
                                                 'healthy gut.'}}]},
   'usage': {'embed_total_tokens': 8, 'read_units': 6}}
  ```

  ```javascript JavaScript theme={null}
  {
    result: { 
      hits: [ 
        {
          _id: 'rec3',
          _score: 0.82042724,
          fields: {
            category: 'immune system',
            chunk_text: 'Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases.'
          }
        },
        {
          _id: 'rec1',
          _score: 0.7931626,
          fields: {
            category: 'digestive system',
            chunk_text: 'Apples are a great source of dietary fiber, which supports digestion and helps maintain a healthy gut.'
          }
        }
      ]
    },
    usage: { 
      readUnits: 6, 
      embedTotalTokens: 8 
    }
  }
  ```

  ```java Java theme={null}
  class SearchRecordsResponse {
      result: class SearchRecordsResponseResult {
          hits: [class Hit {
              id: rec3
              score: 0.8204272389411926
              fields: {category=immune system, chunk_text=Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases.}
              additionalProperties: null
          }, class Hit {
              id: rec1
              score: 0.7931625843048096
              fields: {category=endocrine system, chunk_text=Apples are a great source of dietary fiber, which supports digestion and helps maintain a healthy gut.}
              additionalProperties: null
          }]
          additionalProperties: null
      }
      usage: class SearchUsage {
          readUnits: 6
          embedTotalTokens: 13
      }
      additionalProperties: null
  }
  ```

  ```go Go theme={null}
  {
    "result": {
      "hits": [
        {
          "_id": "rec3",
          "_score": 0.82042724,
          "fields": {
            "category": "immune system",
            "chunk_text": "Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases."
          }
        },
        {
          "_id": "rec1",
          "_score": 0.7931626,
          "fields": {
            "category": "digestive system",
            "chunk_text": "Apples are a great source of dietary fiber, which supports digestion and helps maintain a healthy gut."
          }
        }
      ]
    },
    "usage": {
      "read_units": 6,
      "embed_total_tokens": 8
    }
  }
  ```

  ```json curl theme={null}
   {
      "result": {
          "hits": [
              {
                  "_id": "rec3",
                  "_score": 0.82042724,
                  "fields": {
                      "category": "immune system",
                      "chunk_text": "Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases."
                  }
              },
              {
                  "_id": "rec1",
                  "_score": 0.7931626,
                  "fields": {
                      "category": "digestive system",
                      "chunk_text": "Apples are a great source of dietary fiber, which supports digestion and helps maintain a healthy gut."
                  }
              }
          ]
      },
      "usage": {
          "embed_total_tokens": 8,
          "read_units": 6
      }
  }
  ```
</CodeGroup>

## Search with a dense vector

To search an index of dense vectors with a dense vector representation of a query, use the [`query`](/reference/api/latest/data-plane/query) operation with the following parameters:

* The `namespace` to query. To use the default namespace, set the namespace to `"__default__"`.
* The `vector` parameter with the dense vector values representing your query.
* The `top_k` parameter with the number of results to return.
* Optionally, you can set `include_values` and/or `include_metadata` to `true` to include the vector values and/or metadata of the matching records in the response. For better performance, especially with higher `top_k` values, avoid including vector values unless you need them. See [Decrease latency](/guides/optimize/decrease-latency#avoid-including-vector-values-when-not-needed) for more details.

For example, the following code uses a dense vector representation of the query “Disease prevention” to search for the 3 most semantically similar records in the `example-namespaces` namespace:

<CodeGroup>
  ```Python Python theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")

  # To get the unique host for an index, 
  # see https://docs.pinecone.io/guides/manage-data/target-an-index
  index = pc.Index(host="INDEX_HOST")

  index.query(
      namespace="example-namespace",
      vector=[0.0236663818359375,-0.032989501953125, ..., -0.01041412353515625,0.0086669921875], 
      top_k=3,
      include_metadata=True,
      include_values=False
  )
  ```

  ```JavaScript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone'

  const pc = new Pinecone({ apiKey: "YOUR_API_KEY" })

  // To get the unique host for an index, 
  // see https://docs.pinecone.io/guides/manage-data/target-an-index
  const index = pc.index("INDEX_NAME", "INDEX_HOST")

  const queryResponse = await index.namespace('example-namespace').query({
      vector: [0.0236663818359375,-0.032989501953125,...,-0.01041412353515625,0.0086669921875],
      topK: 3,
      includeValues: false,
      includeMetadata: true,
  });
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Index;
  import io.pinecone.configs.PineconeConfig;
  import io.pinecone.configs.PineconeConnection;
  import io.pinecone.unsigned_indices_model.QueryResponseWithUnsignedIndices;

  import java.util.Arrays;
  import java.util.List;

  public class QueryExample {
      public static void main(String[] args) {
          PineconeConfig config = new PineconeConfig("YOUR_API_KEY");
          // To get the unique host for an index, 
          // see https://docs.pinecone.io/guides/manage-data/target-an-index
          config.setHost("INDEX_HOST");
          PineconeConnection connection = new PineconeConnection(config);
          Index index = new Index(connection, "INDEX_NAME");
          List<Float> query = Arrays.asList(0.0236663818359375f, -0.032989501953125f, ..., -0.01041412353515625f, 0.0086669921875f);
          QueryResponseWithUnsignedIndices queryResponse = index.query(3, query, null, null, null, "example-namespace", null, false, true);
          System.out.println(queryResponse);
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "encoding/json"
      "fmt"
      "log"

      "github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func prettifyStruct(obj interface{}) string {
  	bytes, _ := json.MarshalIndent(obj, "", "  ")
  	return string(bytes)
  }

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

      // To get the unique host for an index, 
      // see https://docs.pinecone.io/guides/manage-data/target-an-index
      idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST", Namespace: "example-namespace"})
      if err != nil {
          log.Fatalf("Failed to create IndexConnection for Host: %v", err)
    	}

      queryVector := []float32{0.0236663818359375,-0.032989501953125,...,-0.01041412353515625,0.0086669921875}

      res, err := idxConnection.QueryByVectorValues(ctx, &pinecone.QueryByVectorValuesRequest{
          Vector:          queryVector,
          TopK:            3,
          IncludeValues:   false,
          includeMetadata: true,
      })
      if err != nil {
          log.Fatalf("Error encountered when querying by vector: %v", err)
      } else {
          fmt.Printf(prettifyStruct(res))
      }
  }
  ```

  ```bash curl theme={null}
  # To get the unique host for an index,
  # see https://docs.pinecone.io/guides/manage-data/target-an-index
  PINECONE_API_KEY="YOUR_API_KEY"
  INDEX_HOST="INDEX_HOST"

  curl "https://$INDEX_HOST/query" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H 'Content-Type: application/json' \
    -H "X-Pinecone-Api-Version: 2025-10" \
    -d '{
          "vector": [0.0236663818359375,-0.032989501953125,...,-0.01041412353515625,0.0086669921875],
          "namespace": "example-namespace",
          "topK": 3,
          "includeMetadata": true,
          "includeValues": false
      }'
  ```
</CodeGroup>

The response will look as follows. Each record is returned with a similarity score that represents its distance to the query vector, calculated according to the [similarity metric](/guides/index-data/create-an-index#similarity-metrics) for the index.

<CodeGroup>
  ```python Python theme={null}
  {'matches': [{'id': 'rec3',
                'metadata': {'category': 'immune system',
                             'chunk_text': 'Rich in vitamin C and other '
                                            'antioxidants, apples contribute to '
                                            'immune health and may reduce the '
                                            'risk of chronic diseases.'},
                'score': 0.82026422,
                'values': []},
               {'id': 'rec1',
                'metadata': {'category': 'digestive system',
                             'chunk_text': 'Apples are a great source of '
                                            'dietary fiber, which supports '
                                            'digestion and helps maintain a '
                                            'healthy gut.'},
                'score': 0.793068111,
                'values': []},
               {'id': 'rec4',
                'metadata': {'category': 'endocrine system',
                             'chunk_text': 'The high fiber content in apples '
                                            'can also help regulate blood sugar '
                                            'levels, making them a favorable '
                                            'snack for people with diabetes.'},
                'score': 0.780169606,
                'values': []}],
   'namespace': 'example-namespace',
   'usage': {'read_units': 6}}
  ```

  ```JavaScript JavaScript theme={null}
  {
    matches: [
      {
        id: 'rec3',
        score: 0.819709897,
        values: [],
        sparseValues: undefined,
        metadata: [Object]
      },
      {
        id: 'rec1',
        score: 0.792900264,
        values: [],
        sparseValues: undefined,
        metadata: [Object]
      },
      {
        id: 'rec4',
        score: 0.780068815,
        values: [],
        sparseValues: undefined,
        metadata: [Object]
      }
    ],
    namespace: 'example-namespace',
    usage: { readUnits: 6 }
  }
  ```

  ```java Java theme={null}
  class QueryResponseWithUnsignedIndices {
      matches: [ScoredVectorWithUnsignedIndices {
          score: 0.8197099
          id: rec3
          values: []
          metadata: fields {
            key: "category"
            value {
              string_value: "immune system"
            }
          }
          fields {
            key: "chunk_text"
            value {
              string_value: "Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases."
            }
          }
          
          sparseValuesWithUnsignedIndices: SparseValuesWithUnsignedIndices {
              indicesWithUnsigned32Int: []
              values: []
          }
      }, ScoredVectorWithUnsignedIndices {
          score: 0.79290026
          id: rec1
          values: []
          metadata: fields {
            key: "category"
            value {
              string_value: "digestive system"
            }
          }
          fields {
            key: "chunk_text"
            value {
              string_value: "Apples are a great source of dietary fiber, which supports digestion and helps maintain a healthy gut."
            }
          }
          
          sparseValuesWithUnsignedIndices: SparseValuesWithUnsignedIndices {
              indicesWithUnsigned32Int: []
              values: []
          }
      }, ScoredVectorWithUnsignedIndices {
          score: 0.7800688
          id: rec4
          values: []
          metadata: fields {
            key: "category"
            value {
              string_value: "endocrine system"
            }
          }
          fields {
            key: "chunk_text"
            value {
              string_value: "The high fiber content in apples can also help regulate blood sugar levels, making them a favorable snack for people with diabetes."
            }
          }
          
          sparseValuesWithUnsignedIndices: SparseValuesWithUnsignedIndices {
              indicesWithUnsigned32Int: []
              values: []
          }
      }]
      namespace: example-namespace
      usage: read_units: 6

  }
  ```

  ```go Go theme={null}
  {
    "matches": [
      {
        "vector": {
          "id": "rec3",
          "metadata": {
            "category": "immune system",
            "chunk_text": "Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases."
          }
        },
        "score": 0.8197099
      },
      {
        "vector": {
          "id": "rec1",
          "metadata": {
            "category": "digestive system",
            "chunk_text": "Apples are a great source of dietary fiber, which supports digestion and helps maintain a healthy gut."
          }
        },
        "score": 0.79290026
      },
      {
        "vector": {
          "id": "rec4",
          "metadata": {
            "category": "endocrine system",
            "chunk_text": "The high fiber content in apples can also help regulate blood sugar levels, making them a favorable snack for people with diabetes."
          }
        },
        "score": 0.7800688
      }
    ],
    "usage": {
      "read_units": 6
    },
    "namespace": "example-namespace"
  }
  ```

  ```json curl theme={null}
  {
      "results": [],
      "matches": [
          {
              "id": "rec3",
              "score": 0.820593238,
              "values": [],
              "metadata": {
                  "category": "immune system",
                  "chunk_text": "Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases."
              }
          },
          {
              "id": "rec1",
              "score": 0.792266726,
              "values": [],
              "metadata": {
                  "category": "digestive system",
                  "chunk_text": "Apples are a great source of dietary fiber, which supports digestion and helps maintain a healthy gut."
              }
          },
          {
              "id": "rec4",
              "score": 0.780045748,
              "values": [],
              "metadata": {
                  "category": "endocrine system",
                  "chunk_text": "The high fiber content in apples can also help regulate blood sugar levels, making them a favorable snack for people with diabetes."
              }
          }
      ],
      "namespace": "example-namespace",
      "usage": {
          "readUnits": 6
      }
  }
  ```
</CodeGroup>

## Search with a record ID

When you search with a record ID, Pinecone uses the dense vector associated with the record as the query. To search an index of dense vectors with a record ID, use the [`query`](/reference/api/latest/data-plane/query) operation with the following parameters:

* The `namespace` to query. To use the default namespace, set the namespace to `"__default__"`.
* The `id` parameter with the unique record ID containing the vector to use as the query.
* The `top_k` parameter with the number of results to return.
* Optionally, you can set `include_values` and/or `include_metadata` to `true` to include the vector values and/or metadata of the matching records in the response. For better performance, especially with higher `top_k` values, avoid including vector values unless you need them. See [Decrease latency](/guides/optimize/decrease-latency#avoid-including-vector-values-when-not-needed) for more details.

For example, the following code uses an ID to search for the 3 records in the `example-namespace` namespace that are most semantically similar to the dense vector in the record:

<CodeGroup>
  ```Python Python theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")

  # To get the unique host for an index, 
  # see https://docs.pinecone.io/guides/manage-data/target-an-index
  index = pc.Index(host="INDEX_HOST")

  index.query(
      namespace="example-namespace",
      id="rec2", 
      top_k=3,
      include_metadata=True,
      include_values=False
  )
  ```

  ```JavaScript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone'

  const pc = new Pinecone({ apiKey: "YOUR_API_KEY" })

  // To get the unique host for an index, 
  // see https://docs.pinecone.io/guides/manage-data/target-an-index
  const index = pc.index("INDEX_NAME", "INDEX_HOST")

  const queryResponse = await index.namespace('example-namespace').query({
      id: 'rec2',
      topK: 3,
      includeValues: false,
      includeMetadata: true,
  });
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Index;
  import io.pinecone.configs.PineconeConfig;
  import io.pinecone.configs.PineconeConnection;
  import io.pinecone.unsigned_indices_model.QueryResponseWithUnsignedIndices;

  public class QueryExample {
      public static void main(String[] args) {
          PineconeConfig config = new PineconeConfig("YOUR_API_KEY");
          // To get the unique host for an index, 
          // see https://docs.pinecone.io/guides/manage-data/target-an-index
          config.setHost("INDEX_HOST");
          PineconeConnection connection = new PineconeConnection(config);
          Index index = new Index(connection, "INDEX_NAME");
          QueryResponseWithUnsignedIndices queryRespone = index.queryByVectorId(3, "rec2", "example-namespace", null, false, true);
          System.out.println(queryResponse);
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "encoding/json"
      "fmt"
      "log"

      "github.com/pinecone-io/go-pinecone/v4/pinecone"
  )

  func prettifyStruct(obj interface{}) string {
  	bytes, _ := json.MarshalIndent(obj, "", "  ")
  	return string(bytes)
  }

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

      // To get the unique host for an index, 
      // see https://docs.pinecone.io/guides/manage-data/target-an-index
      idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST", Namespace: "example-namespace"})
      if err != nil {
          log.Fatalf("Failed to create IndexConnection for Host: %v", err)
    	}

      vectorId := "rec2"
      res, err := idxConnection.QueryByVectorId(ctx, &pinecone.QueryByVectorIdRequest{
          VectorId:      vectorId,
          TopK:          3,
          IncludeValues: false,
          IncludeMetadata: true,
      })
      if err != nil {
          log.Fatalf("Error encountered when querying by vector ID `%v`: %v", vectorId, err)
      } else {
          fmt.Printf(prettifyStruct(res.Matches))
      }
  }
  ```

  ```bash curl theme={null}
  # To get the unique host for an index,
  # see https://docs.pinecone.io/guides/manage-data/target-an-index
  PINECONE_API_KEY="YOUR_API_KEY"
  INDEX_HOST="INDEX_HOST"

  curl "https://$INDEX_HOST/query" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H 'Content-Type: application/json' \
    -H "X-Pinecone-Api-Version: 2025-10" \
    -d '{
          "id": "rec2",
          "namespace": "example-namespace",
          "topK": 3,
          "includeMetadata": true,
          "includeValues": false
      }'
  ```
</CodeGroup>

## Parallel queries

Python SDK v6.0.0 and later provide `async` methods for use with [asyncio](https://docs.python.org/3/library/asyncio.html). Async support makes it possible to use Pinecone with modern async web frameworks such as FastAPI, Quart, and Sanic, and can significantly increase the efficiency of running queries in parallel. For more details, see the [Async requests](/reference/sdks/python/overview#async-requests).

Alternatively, you can run multi-threaded, synchronous queries in parallel. For example, the following code uses a thread pool to run multiple queries concurrently. This example assumes that you have a 1536-dimension serverless index called `docs-example` and the [Pinecone Python SDK](/reference/sdks/python/overview) and [`concurrent.futures`](https://docs.python.org/3/library/concurrent.futures.html#module-concurrent.futures) and [`numpy`](https://numpy.org/) packages installed.

```python theme={null}
import os
from pinecone import Pinecone
from concurrent.futures import ThreadPoolExecutor

# Get the API key from the environment variable and initialize Pinecone
api_key = os.environ.get("PINECONE_API_KEY")
pc = Pinecone(api_key=api_key)

# Define the index name
index_name = "docs-example"

# Define the index
index = pc.Index(index_name)

# Define the function to run parallel queries
def run_parallel_queries(vectors):
    """
    Run a list of vectors in parallel using ThreadPoolExecutor.
    
    Parameters:
    vectors (list): A list of vectors.
    
    Returns:
    list: A list of query results.
    """
    
    # Define the maximum number of concurrent queries
    MAX_CONCURRENT_QUERIES = 4

    def run_query(vector):
        """
        Run a single query.
        """
        return index.query(
            namespace="example-namespace",
            vector=vector,
            top_k=3,
            include_values=True
        )
    
    # Run the queries in parallel
    with ThreadPoolExecutor(max_workers=MAX_CONCURRENT_QUERIES) as executor:
        results = list(executor.map(run_query, vectors))
    
    return results

def test_parallel_queries():
    """
    Test the run_parallel_queries function with 20 random vectors.
    """
    import numpy as np

    # Generate 20 random vectors of size 1536 and convert them to lists
    vectors = [np.random.rand(1536).tolist() for _ in range(20)]

    # Run the parallel queries
    results = run_parallel_queries(vectors)

    # Print the results
    for i, result in enumerate(results):
        print(f"Query {i+1} results: {result}")

if __name__ == "__main__":
    test_parallel_queries()
```


# Authentication
Source: https://docs.pinecone.io/reference/api/authentication

Pinecone API authentication guide covering API key generation, SDK client setup, and HTTP header configuration for authorized requests.

All requests to [Pinecone APIs](/reference/api/introduction) must contain a valid [API key](/guides/production/security-overview#api-keys) for the target project.

## Get an API key

[Create a new API key](https://app.pinecone.io/organizations/-/projects/-/keys) in the Pinecone console, or use the connect widget below to generate a key.

<div>
  <div>
    <div>
      <div />
    </div>
  </div>
</div>

Copy your generated key:

```
PINECONE_API_KEY="{{YOUR_API_KEY}}"

# This API key has ReadWrite access to all indexes in your project.
```

## Initialize a client

When using a [Pinecone SDK](/reference/pinecone-sdks), initialize a client object with your API key and then reuse the authenicated client in subsquent function calls. For example:

<CodeGroup>
  ```Python Python theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone
  from pinecone import ServerlessSpec

  pc = Pinecone(api_key='YOUR_API_KEY')

  # Creates an index using the API key stored in the client 'pc'.
  pc.create_index(
      name="docs-example",
      dimension=1536,
      metric="cosine",
      spec=ServerlessSpec(
          cloud='aws', 
          region='us-east-1'
      ) 
  ) 
  ```

  ```JavaScript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone';

  const pc = new Pinecone({
      apiKey: 'YOUR_API_KEY' 
  });

  // Creates an index using the API key stored in the client 'pc'.
  await pc.createIndex({
      name: 'docs-example',
      dimension: 1536,
      metric: 'cosine',
      spec: { 
          serverless: { 
              cloud: 'aws', 
              region: 'us-east-1' 
          }
      } 
  }) 
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Pinecone;
  import org.openapitools.db_control.client.model.IndexModel;
  import org.openapitools.db_control.client.model.DeletionProtection;

  public class CreateServerlessIndexExample {
      public static void main(String[] args) {
          Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build();

          // Creates an index using the API key stored in the client 'pc'.
          pc.createServerlessIndex("docs-example", "cosine", 1536, "aws", "us-east-1");
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "fmt"
      "log"

      "github.com/pinecone-io/go-pinecone/v3/pinecone"
  )

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

  	indexName := "docs-example"
  	vectorType := "dense"
      dimension := int32(1536)
      metric := pinecone.Cosine
  	deletionProtection := pinecone.DeletionProtectionDisabled

      idx, err := pc.CreateServerlessIndex(ctx, &pinecone.CreateServerlessIndexRequest{
          Name:               indexName,
          VectorType:         &vectorType,
          Dimension:          &dimension,
          Metric:             &metric,
          Cloud:              pinecone.Aws,
          Region:             "us-east-1",
          DeletionProtection: &deletionProtection,
      })
      if err != nil {
          log.Fatalf("Failed to create serverless index: %v", err)
      } else {
          fmt.Printf("Successfully created serverless index: %v", idx.Name)
      }
  }
  ```

  ```shell curl theme={null}
  curl -s "https://api.pinecone.io/indexes" \
      -H "Api-Key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -H "X-Pinecone-Api-Version: 2025-10" \
      -d '{
          "name":  "docs-example",
          "dimension": 1536,
          "metric": "cosine",
          "spec": {
              "serverless": {
                 "cloud":"aws",
                 "region": "us-east-1"
              }
          }
      }'
  ```
</CodeGroup>

## Add headers to an HTTP request

All HTTP requests to Pinecone APIs must contain an `Api-Key` header that specifies a valid [API key](/guides/production/security-overview#api-keys) and must be encoded as JSON with the `Content-Type: application/json` header. For example:

```shell curl theme={null}
curl https://api.pinecone.io/indexes \
   -H "Content-Type: application/json" \
   -H "Api-Key: $PINECONE_API_KEY" \
  -H "X-Pinecone-Api-Version: 2025-10" \
   -d '{
         "name":  "docs-example",
         "dimension": 1536,
         "metric": "cosine",
         "spec": {
            "serverless": {
               "cloud":"aws",
               "region": "us-east-1"
            }
         }
      }'
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Initialization errors due to outdated SDKs">
    Older versions of Pinecone required you to initialize a client with an `init` method that takes both `api_key` and `environment` parameters, for example:

    <CodeGroup>
      ```python Python theme={null}
      # Legacy initialization
      import pinecone

      pc = pinecone.init(
          api_key="PINECONE_API_KEY",
          environment="PINECONE_ENVIRONMENT"
      )
      ```

      ```javascript JavaScript theme={null}
      // Legacy initialization
      import { Pinecone } from '@pinecone-database/pinecone';

      const pineconeClient = new PineconeClient();
      await pineconeClient.init({
          apiKey: 'PINECONE_API_KEY',
          environment: 'PINECONE_ENVIRONMENT',
      });
      ```
    </CodeGroup>

    In more recent versions of Pinecone, this has changed. Initialization no longer requires an `init` step, and cloud environment is defined for each index rather than an entire project. Client initialization now only requires an `api_key` parameter, for example:

    <CodeGroup>
      ```python Python theme={null}
      # New initialization
      from pinecone import Pinecone

      pc = Pinecone(api_key="YOUR_API_KEY")
      ```

      ```javascript JavaScript theme={null}
      // New initialization
      import { Pinecone } from '@pinecone-database/pinecone';

      const pc = new Pinecone({
          apiKey: 'YOUR_API_KEY' 
      });
      ```
    </CodeGroup>

    If you are receiving errors about initialization, upgrade your [Pinecone SDK](/reference/pinecone-sdks) to the latest version, for example:

    <CodeGroup>
      ```shell Python theme={null}
      # Upgrade Pinecone SDK
      pip install pinecone --upgrade
      ```

      ```shell JavaScript theme={null}
      # Upgrade Pinecone SDK
      npm install @pinecone-database/pinecone@latest
      ```
    </CodeGroup>

    Also, note that some third-party tutorials and examples still reference the older initialization method. In such cases, follow the example above and the examples throughout the Pinecone documentation instead.
  </Accordion>
</AccordionGroup>


# Pinecone Database limits
Source: https://docs.pinecone.io/reference/api/database-limits

Reference for Pinecone Database limits, covering upsert, query, fetch, delete, import, namespace, and rate limits for serverless indexes.

This page describes different types of limits for Pinecone Database.

<Note>
  **Looking for a specific limit?**

  * To compare monthly included usage by plan, start with [read units](#read-units-per-month-per-org), [write units](#write-units-per-month-per-org), and [model usage limits](#monthly-usage-limits).
  * If you received a `429` error, check [rate limits](#rate-limits), especially request-per-second limits for query, upsert, update, delete, fetch, and list.
  * For projects, users, indexes, namespaces, storage, backups, and collections, see [object limits](#object-limits).
  * For batch sizes, metadata filters, and identifier lengths, see [operation limits](#operation-limits) and [identifier limits](#identifier-limits).
</Note>

## Rate limits

Rate limits help protect your applications from misuse and maintain the health of our shared serverless infrastructure. These limits are designed to support typical production workloads while ensuring reliable performance for all users.

**Most rate limits can be adjusted upon request.** If you need higher limits to scale your application, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) with details about your use case. Pinecone is committed to supporting your growth and can often accommodate higher throughput requirements.

Rate limits vary based on [pricing plan](https://www.pinecone.io/pricing/) and apply to [serverless indexes](/guides/index-data/indexing-overview) only.

<Note>
  Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide.
</Note>

### Data plane operations: request-per-second limits

Pinecone enforces rate limits on the number of API requests per second at the namespace level for data plane operations (query, upsert, delete, and update). These limits provide protection against excessive request rates.

#### Affected operations

The following operations are subject to request-per-second rate limiting:

| Operation | Scope         | Limit |
| --------- | ------------- | ----- |
| Query     | Per namespace | 100   |
| Upsert    | Per namespace | 100   |
| Delete    | Per namespace | 100   |
| Update    | Per namespace | 100   |

#### Error response

When you exceed the request-per-second limit, you'll receive an HTTP `429 - TOO_MANY_REQUESTS` response. The error message indicates which operation exceeded the limit and includes the namespace name and limit value. See the individual limit sections below for specific error message formats.

#### How request-per-second limits work with limits on read and write units

Request-per-second limits are enforced in addition to existing read unit and write unit limits. Requests must not exceed any applicable limits:

* Index-level limits - read and write unit limits, per index
* Namespace-level limits - read and write unit limits, per namespace
* Request-per-second limits - requests per second, per namespace

If any limit is exceeded, the request fails with a 429 error.

#### Recommendations

If you're hitting request-per-second limits:

1. Implement retry logic. Use exponential backoff to handle rate limit errors gracefully. See [Error Handling Guide](/guides/production/error-handling#implement-retry-logic).
2. Pace your requests. Add client-side rate limiting to stay under limits.
3. Consider [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes), which don't have request-per-second limits and provide dedicated capacity for high-throughput workloads.
4. If you need higher limits, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) with details about your use case.

### All rate limits

#### Monthly usage limits

| Metric                                                                        | Starter plan   | Builder plan   | Standard plan  | Enterprise plan |
| :---------------------------------------------------------------------------- | :------------- | :------------- | :------------- | :-------------- |
| [Read units per month per org](#read-units-per-month-per-org)                 | 1,000,000      | 2,000,000      | Unlimited      | Unlimited       |
| [Write units per month per org](#write-units-per-month-per-org)               | 2,000,000      | 5,000,000      | Unlimited      | Unlimited       |
| [Embedding tokens per month per model](#embedding-tokens-per-month-per-model) | 5,000,000      | 10,000,000     | Unlimited      | Unlimited       |
| [Rerank requests per month per model](#rerank-requests-per-month-per-model)   | Model-specific | Model-specific | Model-specific | Model-specific  |

#### Data operation throughput limits

| Metric                                                                                                        | Starter plan | Builder plan | Standard plan | Enterprise plan |
| :------------------------------------------------------------------------------------------------------------ | :----------- | :----------- | :------------ | :-------------- |
| [Upsert size per second per namespace](#upsert-size-per-second-per-namespace)                                 | 50 MB        | 50 MB        | 50 MB         | 50 MB           |
| [Query read units per second per index](#query-read-units-per-second-per-index)                               | 2,000        | 2,000        | 2,000         | 2,000           |
| [Query requests per second per namespace](#query-requests-per-second-per-namespace)                           | 100          | 100          | 100           | 100             |
| [Update records per second per namespace](#update-records-per-second-per-namespace)                           | 100          | 100          | 100           | 100             |
| [Update requests per second per namespace](#update-requests-per-second-per-namespace)                         | 100          | 100          | 100           | 100             |
| [Update by metadata requests per second per namespace](#update-by-metadata-requests-per-second-per-namespace) | 5            | 5            | 5             | 5               |
| [Update by metadata requests per second per index](#update-by-metadata-requests-per-second-per-index)         | 500          | 500          | 500           | 500             |
| [Upsert requests per second per namespace](#upsert-requests-per-second-per-namespace)                         | 100          | 100          | 100           | 100             |
| [Fetch requests per second per index](#fetch-requests-per-second-per-index)                                   | 100          | 100          | 100           | 100             |
| [List requests per second per index](#list-requests-per-second-per-index)                                     | 200          | 200          | 200           | 200             |
| [Describe index stats requests per second per index](#describe-index-stats-requests-per-second-per-index)     | 100          | 100          | 100           | 100             |
| [Delete requests per second per namespace](#delete-requests-per-second-per-namespace)                         | 100          | 100          | 100           | 100             |
| [Delete records per second per namespace](#delete-records-per-second-per-namespace)                           | 5,000        | 5,000        | 5,000         | 5,000           |
| [Delete records per second per index](#delete-records-per-second-per-index)                                   | 5,000        | 5,000        | 5,000         | 5,000           |
| [Delete by metadata requests per second per namespace](#delete-by-metadata-requests-per-second-per-namespace) | 5            | 5            | 5             | 5               |
| [Delete by metadata requests per second per index](#delete-by-metadata-requests-per-second-per-index)         | 500          | 500          | 500           | 500             |

#### Model throughput limits

| Metric                                                                          | Starter plan   | Builder plan   | Standard plan  | Enterprise plan |
| :------------------------------------------------------------------------------ | :------------- | :------------- | :------------- | :-------------- |
| [Embedding tokens per minute per model](#embedding-tokens-per-minute-per-model) | Model-specific | Model-specific | Model-specific | Model-specific  |
| [Rerank requests per minute per model](#rerank-requests-per-minute-per-model)   | Model-specific | Model-specific | Model-specific | Model-specific  |

### Read units per month per org

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 1,000,000    | 2,000,000    | Unlimited     | Unlimited       |

[Read units](/guides/manage-cost/understanding-cost#read-units) measure the compute, I/O, and network resources used by [fetch](/guides/manage-data/fetch-data), [query](/guides/search/search-overview), and [list](/guides/manage-data/list-record-ids) requests to serverless indexes. When you reach the monthly read unit limit for an organization, fetch, query, and list requests to serverless indexes in the organization will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached your read unit limit for the current month limit. 
  To continue reading data, upgrade your plan. 
  ```
</Accordion>

To continue reading from serverless indexes in the organization, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan).

To check how close you are to the monthly read unit limit for your organization, do the following:

1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects).
2. Select the project.
3. Select any index in the project.
4. Look under **Usage**.

<Note>
  Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide.
</Note>

### Write units per month per org

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 2,000,000    | 5,000,000    | Unlimited     | Unlimited       |

[Write units](/guides/manage-cost/understanding-cost#write-units) measure the storage and compute resources used by [upsert](/guides/index-data/upsert-data), [update](/guides/manage-data/update-data), and [delete](/guides/manage-data/delete-data) requests to serverless indexes. When you reach the monthly write unit limit for an organization, upsert, update, and delete requests to serverless indexes in the organization will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached your write unit limit for the current month. 
  To continue writing data, upgrade your plan.
  ```
</Accordion>

To continue writing data to serverless indexes in the organization, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan).

To check how close you are to the monthly write unit limit for your organization, do the following:

1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects).
2. Select the project.
3. Select any index in the project.
4. Look under **Usage**.

### Upsert size per second per namespace

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 50 MB        | 50 MB        | 50 MB         | 50 MB           |

When you reach the per second [upsert](/guides/index-data/upsert-data) size for a namespace in an index, additional upserts will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max upsert size limit per second for index <index name>. 
  Pace your upserts or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Query read units per second per index

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 2,000        | 2,000        | 2,000         | 2,000           |

Pinecone measures [query](/guides/search/search-overview) usage in [read units](/guides/manage-cost/understanding-cost#read-units). When you reach the per second limit for queries across all namespaces in an index, additional queries will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max query read units per second for index <index name>. 
  Pace your queries or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

To check how many read units a query consumes, [check the query response](/guides/manage-cost/monitor-usage-and-costs#read-units).

<Note>
  Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide.
</Note>

### Query requests per second per namespace

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 100          | 100          | 100           | 100             |

When you reach the per second [query](/guides/search/search-overview) limit for a namespace in an index, additional queries will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the query QPS limit for namespace {namespace_name} ({limit} QPS). Pace your queries,
  consider Dedicated Read Nodes for your index, or contact Pinecone Support
  (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

<Note>
  Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide.
</Note>

### Update records per second per namespace

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 100          | 100          | 100           | 100             |

When you reach the per second [update](/guides/manage-data/update-data) limit for a namespace in an index, additional updates will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max update records per second for namespace <namespace name>. 
  Pace your update requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Update requests per second per namespace

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 100          | 100          | 100           | 100             |

When you reach the per second [update](/guides/manage-data/update-data) request limit for a namespace in an index, additional update requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the update QPS limit for namespace {namespace_name} ({limit} QPS). Pace your update requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

<Tip>
  If you need to update most of the records in a large namespace, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) for help creating an export to enable a faster and more cost-effective approach.
</Tip>

### Update by metadata requests per second per namespace

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 5            | 5            | 5             | 5               |

When you reach the per second [update by metadata](/guides/manage-data/update-data#update-metadata-across-multiple-records) request limit for a namespace in an index, additional update by metadata requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max update by metadata requests per second for namespace <namespace name>. Pace your update by metadata requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Update by metadata requests per second per index

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 500          | 500          | 500           | 500             |

When you reach the per second [update by metadata](/guides/manage-data/update-data#update-metadata-across-multiple-records) request limit across all namespaces in an index, additional update by metadata requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max update by metadata requests per second for index <index name>. Pace your update by metadata requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Upsert requests per second per namespace

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 100          | 100          | 100           | 100             |

When you reach the per second [upsert](/guides/index-data/upsert-data) request limit for a namespace in an index, additional upsert requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the upsert QPS limit for namespace {namespace_name} ({limit} QPS). Pace your upsert requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Fetch requests per second per index

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 100          | 100          | 100           | 100             |

When you reach the per second [fetch](/guides/manage-data/fetch-data) limit across all namespaces in an index, additional fetch requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max fetch requests per second for index <index name>.
  Pace your fetch requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

<Note>
  Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide.
</Note>

### List requests per second per index

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 200          | 200          | 200           | 200             |

When you reach the per second [list](/guides/manage-data/list-record-ids) limit across all namespaces in an index, additional list requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max list requests per second for index <index name>.
  Pace your list requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

<Note>
  Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide.
</Note>

### Describe index stats requests per second per index

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 100          | 100          | 100           | 100             |

When you reach the per second [describe index stats](/reference/api/2024-10/data-plane/describeindexstats) limit across all namespaces in an index, additional describe index stats requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max describe_index_stats requests per second for index <index>. 
  Pace your describe_index_stats requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Delete requests per second per namespace

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 100          | 100          | 100           | 100             |

When you reach the per second [delete](/guides/manage-data/delete-data) request limit for a namespace in an index, additional delete requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the delete QPS limit for namespace {namespace_name} ({limit} QPS). Pace your delete requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Delete records per second per namespace

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 5000         | 5000         | 5000          | 5000            |

When you reach the per second [delete](/guides/manage-data/delete-data) limit for a namespace in an index, additional deletes will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max delete records per second for namespace <namespace name>. 
  Pace your delete requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Delete records per second per index

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 5000         | 5000         | 5000          | 5000            |

When you reach the per second [delete](/guides/manage-data/delete-data) limit across all namespaces in an index, additional deletes will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max delete records per second for index <index name>. 
  Pace your delete requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Delete by metadata requests per second per namespace

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 5            | 5            | 5             | 5               |

When you reach the per second [delete by metadata](/guides/manage-data/delete-data#delete-records-by-metadata) request limit for a namespace in an index, additional delete by metadata requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max delete by metadata requests per second for namespace <namespace name>. Pace your delete by metadata requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Delete by metadata requests per second per index

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 500          | 500          | 500           | 500             |

When you reach the per second [delete by metadata](/guides/manage-data/delete-data#delete-records-by-metadata) request limit across all namespaces in an index, additional delete by metadata requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max delete by metadata requests per second for index <index name>. Pace your delete by metadata requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Embedding tokens per minute per model

| Embedding model              | Input type | Starter plan | Builder plan | Standard plan | Enterprise plan |
| :--------------------------- | :--------- | :----------- | :----------- | :------------ | :-------------- |
| `llama-text-embed-v2`        | Passage    | 250,000      | 250,000      | 1,000,000     | 1,000,000       |
|                              | Query      | 50,000       | 50,000       | 250,000       | 250,000         |
| `multilingual-e5-large`      | Passage    | 250,000      | 250,000      | 1,000,000     | 1,000,000       |
|                              | Query      | 50,000       | 50,000       | 250,000       | 250,000         |
| `pinecone-sparse-english-v0` | Passage    | 250,000      | 250,000      | 3,000,000     | 3,000,000       |
|                              | Query      | 250,000      | 250,000      | 3,000,000     | 3,000,000       |

When you reach the per minute token limit for an [embedding model](/guides/index-data/create-an-index#embedding-models) hosted by Pinecone, additional embeddings will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max embedding tokens per minute (<limit>) model '<model name>'' and input type '<passage|query>' for the current project. 
  To increase this limit, upgrade your plan.
  ```
</Accordion>

To increase this limit, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). Otherwise, you can handle this limit by [implementing retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic).

### Embedding tokens per month per model

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 5,000,000    | 10,000,000   | Unlimited     | Unlimited       |

When you reach the monthly token limit for an [embedding model](/guides/index-data/create-an-index#embedding-models) hosted by Pinecone, additional embeddings will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the embedding token limit (<limit>) for model <model name> for the current month. 
  To continue using this model, upgrade your plan.
  ```
</Accordion>

To increase this limit, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan) or [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Rerank requests per minute per model

| Reranking model        | Starter plan  | Builder plan  | Standard plan | Enterprise plan |
| :--------------------- | :------------ | :------------ | :------------ | :-------------- |
| `cohere-rerank-4-fast` | Not available | Not available | 300           | 300             |
| `cohere-rerank-3.5`    | Not available | Not available | 300           | 300             |
| `bge-reranker-v2-m3`   | 60            | 60            | 60            | 60              |
| `pinecone-rerank-v0`   | 60            | Not available | 60            | 60              |

When you reach the per minute request limit for a [reranking model](/guides/search/rerank-results#reranking-models) hosted by Pinecone, additional reranking requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max rerank requests per minute (<limit>) for model '<model name>' for the current project. 
  To increase this limit, upgrade your plan.
  ```
</Accordion>

To increase this limit, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan).

### Rerank requests per month per model

| Reranking model        | Starter plan  | Builder plan  | Standard plan | Enterprise plan |
| :--------------------- | :------------ | :------------ | :------------ | :-------------- |
| `cohere-rerank-4-fast` | Not available | Not available | Unlimited     | Unlimited       |
| `cohere-rerank-3.5`    | Not available | Not available | Unlimited     | Unlimited       |
| `bge-reranker-v2-m3`   | 500           | 1,000         | Unlimited     | Unlimited       |
| `pinecone-rerank-v0`   | 500           | Not available | Unlimited     | Unlimited       |

When you reach the monthly request limit for a [reranking model](/guides/search/rerank-results#reranking-models) hosted by Pinecone, additional reranking requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the rerank request limit (<limit>) for model <model name> for the current month. 
  To continue using this model, upgrade your plan.
  ```
</Accordion>

To increase this limit, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan) or [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Inference requests per second or minute, per project

| Metric                        | Starter plan | Builder plan | Standard plan | Enterprise plan |
| :---------------------------- | :----------- | :----------- | :------------ | :-------------- |
| Inference requests per second | 100          | 100          | 100           | 100             |
| Inference requests per minute | 2000         | 2000         | 2000          | 2000            |

When you reach the per second or per minute request limit, inference requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max inference requests per second (<limit>) for the current project.
  ```
</Accordion>

<Note>
  This error indicates per second or per minute, as applicable.
</Note>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic).

## Object limits

Object limits are restrictions on the number or size of objects in Pinecone. Object limits vary based on [pricing plan](https://www.pinecone.io/pricing/).

| Metric                                                                         | Starter plan | Builder plan | Standard plan | Enterprise plan |
| :----------------------------------------------------------------------------- | :----------- | :----------- | :------------ | :-------------- |
| [Projects per organization](#projects-per-organization)                        | 1            | 5            | 20            | 100             |
| [Users per organization](#users-per-organization)                              | 2            | 5            | Unlimited     | Unlimited       |
| [Serverless indexes per project](#serverless-indexes-per-project) <sup>1</sup> | 5            | 10           | 20            | 200             |
| [Serverless index storage per org](#serverless-index-storage-per-org)          | 2 GB         | 10 GB        | N/A           | N/A             |
| [Namespaces per serverless index](#namespaces-per-serverless-index)            | 100          | 1,000        | 100,000       | 100,000         |
| [Serverless backups per project](#serverless-backups-per-project)              | N/A          | N/A          | 500           | 1000            |
| [Collections per project](#collections-per-project)                            | 100          | N/A          | N/A           | N/A             |

<sup>1 On the Starter plan, all serverless indexes must be in the `us-east-1` region of AWS. Builder, Standard, and Enterprise plans can create indexes in any [supported region](/guides/index-data/create-an-index#cloud-regions).</sup><br />

### Projects per organization

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 1            | 5            | 20            | 100             |

When you reach this quota for an organization, trying to [create projects](/guides/projects/create-a-project) will fail and return a `403 - QUOTA_EXCEEDED` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max projects allowed in organization <org name>. 
  To add more projects, upgrade your plan.
  ```
</Accordion>

To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan) or [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Users per organization

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 2            | 5            | Unlimited     | Unlimited       |

When you reach this quota for an organization, trying to add users to the organization will fail. To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan).

### Serverless indexes per project

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 5            | 10           | 20            | 200             |

When you reach this quota for a project, trying to [create serverless indexes](/guides/index-data/create-an-index#create-a-serverless-index) in the project will fail and return a `403 - QUOTA_EXCEEDED` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max serverless indexes allowed in project <project>. 
  Use namespaces to partition your data into logical groups, or upgrade your plan to add more serverless indexes.
  ```
</Accordion>

To stay under this quota, consider using [namespaces](/guides/index-data/create-an-index#namespaces) instead of creating multiple indexes. Namespaces let you partition your data into logical groups within a single index. This approach not only helps you stay within index limits, but can also improve query performance and lower costs by limiting searches to relevant data subsets.

To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan).

### Serverless index storage per org

<Note>This limit applies to organizations on the Starter and Builder plans only.</Note>

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 2 GB         | 10 GB        | N/A           | N/A             |

When you've reached this quota for an organization, updates and upserts into serverless indexes will fail and return a `403 - QUOTA_EXCEEDED` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max storage allowed for organization <org name>. 
  To update or upsert new data, delete records or upgrade your plan.
  ```
</Accordion>

To continue writing data into your serverless indexes, [delete records](/guides/manage-data/delete-data) to bring your organization under the limit or [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan).

### Namespaces per serverless index

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 100          | 1,000        | 100,000       | 100,000         |

When you reach this quota for a serverless index, trying to [upsert records into a new namespace](/guides/index-data/upsert-data) in the index will fail and return a `403 - QUOTA_EXCEEDED` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max namespaces allowed in serverless index <index name>. 
  To add more namespaces, upgrade your plan.
  ```
</Accordion>

To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan).

<Note>
  [Namespaces per serverless index](/reference/api/database-limits#namespaces-per-serverless-index) vary by plan. On the Standard and Enterprise plans, Pinecone can accommodate million-scale namespaces and beyond for specific use cases. If your application requires more than 100,000 namespaces, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).
</Note>

### Serverless backups per project

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| N/A          | N/A          | 500           | 1000            |

Backups are not available on the Starter or Builder plans. On the Standard and Enterprise plans, when you reach this quota for a project, trying to [create serverless backups](/guides/manage-data/back-up-an-index) in the project will fail and return a `403 - QUOTA_EXCEEDED` status with the following error:

<Accordion title="Error response">
  ```
  Backup failed to create. Quota for number of backups per index exceeded.
  ```
</Accordion>

### Collections per project

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 100          | N/A          | N/A           | N/A             |

When you reach this quota for a project, trying to [create collections](/guides/manage-data/back-up-an-index) in the project will fail and return a `403 - QUOTA_EXCEEDED` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max collections allowed in project <project name>. 
  To add more collections, upgrade your plan.
  ```
</Accordion>

To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan).

## Operation limits

Operation limits are restrictions on the size, number, or other characteristics of operations in Pinecone. Operation limits are fixed and do not vary based on pricing plan.

### Upsert limits

| Metric                                                             | Limit                                                         |
| :----------------------------------------------------------------- | :------------------------------------------------------------ |
| Max [batch size](/guides/index-data/upsert-data#upsert-in-batches) | 2 MB or 1000 records with vectors <br /> 96 records with text |
| Max documents per upsert request                                   | 1000                                                          |
| Max document upsert request size                                   | 2 MB                                                          |
| Max document size                                                  | 2 MB                                                          |
| Max `full_text_search` string fields per schema                    | 100                                                           |
| Max size per `full_text_search` string field                       | 100 KB                                                        |
| Max tokens per `full_text_search` string field                     | 10,000                                                        |
| Max bytes per token                                                | 256 bytes                                                     |
| Max filterable metadata size per document                          | 40 KB                                                         |
| Max length for a record ID                                         | 512 characters                                                |
| Max dimensionality for dense vectors                               | 20,000                                                        |
| Max non-zero values for sparse vectors                             | 2048                                                          |
| Max dimensionality for sparse vectors                              | 4.2 billion                                                   |

The 40 KB filterable metadata limit does not apply to `full_text_search` text fields.

### Import limits

<Note>
  If your import exceeds these limits, you'll get an error specifying the limit exceeded. See [Troubleshooting](/guides/index-data/import-data#troubleshooting) for details.
</Note>

| Metric                                        | Limit     |
| :-------------------------------------------- | :-------- |
| Max namespaces per import                     | 10,000    |
| Max total input data size (on-demand indexes) | 1 TB      |
| Max total input data size (DRN indexes)       | Unlimited |
| Max files per import                          | 100,000   |
| Max size per file                             | 10 GB     |

The total input data size limit does not apply to indexes with [dedicated read nodes](/guides/index-data/dedicated-read-nodes).

Bulk import supports indexes without a schema definition (Parquet files) and indexes with document schemas ([JSONL files](/guides/search/full-text-search#bulk-import)). Semantic-text (auto-embedded) fields are not yet supported in document schemas.

### Query limits

| Metric            | Limit  |
| :---------------- | :----- |
| Max `top_k` value | 10,000 |
| Max result size   | 4MB    |

The query result size is affected by the dimension of the dense vectors and whether or not dense vector values and metadata are included in the result.

<Tip>
  If a query fails due to exceeding the 4MB result size limit, choose a lower `top_k` value, or use `include_metadata=False` or `include_values=False` to exclude metadata or values from the result. For better performance, especially with higher `top_k` values, avoid including vector values unless you need them.
</Tip>

### Fetch limits

**Fetch by ID limits:**

| Metric                           | Limit |
| :------------------------------- | :---- |
| Max record IDs per fetch request | 1,000 |

**Fetch by metadata limits:**

| Metric                   | Limit                               |
| :----------------------- | :---------------------------------- |
| Max records per response | 10,000                              |
| Max response size        | 4 MB                                |
| Max request rate         | 5 requests per second per namespace |

To retrieve more than 10,000 matching records, paginate through results using the `paginationToken` parameter. See [Fetch records by metadata](/guides/manage-data/fetch-data#fetch-records-by-metadata).

### Delete limits

| Metric                            | Limit |
| :-------------------------------- | :---- |
| Max record IDs per delete request | 1,000 |

### Metadata filter limits

The following limits apply to [metadata filter expressions](/guides/search/filter-by-metadata#metadata-filter-expressions) used in query, delete, update, and fetch operations.

| Limit                                       | Value  | Description                                                                                                                                                                                                      |
| :------------------------------------------ | :----- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Maximum values per `$in` or `$nin` operator | 10,000 | Each `$in` or `$nin` operator accepts up to 10,000 values in its array. This limit applies per operator—if you have multiple `$in` operators in a single filter, each is independently limited to 10,000 values. |

When you exceed this limit, the request will fail and return a `400 - BAD_REQUEST` error.

#### Rationale

Large `$in` operators can impact query performance and cost. Filters with thousands of values increase request payload size and end-to-end latency. Additionally, using large filters typically indicates a shared namespace architecture, which increases query costs—queries scan the entire namespace regardless of filters.

#### Alternative approaches

If you need to filter by more than 10,000 values, consider these alternatives:

* **Use namespaces for tenant isolation**: Instead of filtering by tenant IDs within a single namespace, create separate namespaces for each tenant or tenant group. This can also reduce query costs. See [Design for multi-tenancy](/guides/index-data/data-modeling#design-for-multi-tenancy).
* **Use broader access control groups**: Instead of filtering by individual user IDs, filter by organization, project, or role. This reduces the number of values in your `$in` filter. See [Design for multi-tenancy](/guides/index-data/data-modeling#use-access-control-groups-instead-of-individual-ids).
* **Post-filter client-side**: Retrieve a larger top K without filtering (for example, top 1000), then filter results client-side.
* **Run multiple queries**: Split your filter into multiple queries with smaller `$in` operators and combine the results client-side.

<Tip>
  To avoid hitting this limit in production, validate the size of your `$in` and `$nin` arrays in your application code before making the request to Pinecone.
</Tip>

## Identifier limits

An identifier is a string of characters used to identify "named" [objects in Pinecone](/guides/get-started/concepts). The following Pinecone objects use strings as identifiers:

| Object                                                    | Field       | Max # characters | Allowed characters                                                                                                                        |
| --------------------------------------------------------- | ----------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| [Organization](/guides/get-started/concepts#organization) | `name`      | 512              | <ul><li>UTF-8 except `\0`</li><li>Cannot be empty</li></ul>                                                                               |
| [Project](/guides/get-started/concepts#project)           | `name`      | 512              | <ul><li>UTF-8 except `\0`</li><li>Cannot be empty</li></ul>                                                                               |
| [Index](/guides/get-started/concepts#index)               | `name`      | 45               | <ul><li>`a-z`, `0-9`, and `-`</li><li>Must be lowercase</li><li>Cannot start or end with `-`</li><li>Cannot be empty</li></ul>            |
| [Namespace](/guides/get-started/concepts#namespace)       | `namespace` | 512              | <ul><li>ASCII except `\0`</li><li>For the default namespace, use `""` (or `"__default__"`, in API versions `2025-04` and later)</li></ul> |
| [Record](/guides/get-started/concepts#record)             | `id`        | 512              | <ul><li>ASCII except `\0`</li><li>Cannot be empty</li></ul>                                                                               |


# Errors
Source: https://docs.pinecone.io/reference/api/errors

Pinecone REST API: Pinecone uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the range.

Pinecone uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the `2xx` range indicate success, codes in the `4xx` range indicate an error that failed given the information provided, and codes in the `5xx` range indicate an error with Pinecone's servers.

For guidance on handling errors in production, see [Error handling](/guides/production/error-handling).

## 200 - OK

The request succeeded.

## 201 - CREATED

The request succeeded and a new resource was created.

## 202 - NO CONTENT

The request succeeded, but there is no content to return.

## 400 - INVALID ARGUMENT

The request failed due to an invalid argument.

## 401 - UNAUTHENTICATED

The request failed due to a missing or invalid [API key](/guides/projects/understanding-projects#api-keys).

## 402 - PAYMENT REQUIRED

The request failed due to delinquent payment or account deactivation for non-payment. See [Account deactivation for non-payment](/guides/organizations/manage-billing/non-payment-account-deactivation).

## 403 - FORBIDDEN

The request failed due to an exceeded [quota](/reference/api/database-limits#object-limits) or [index deletion protection](/guides/manage-data/manage-indexes#configure-deletion-protection).

## 404 - NOT FOUND

The request failed because the resource was not found.

## 409 - ALREADY EXISTS

The request failed because the resource already exists.

## 412 - FAILED PRECONDITIONS

The request failed due to preconditions not being met. |

## 422 - UNPROCESSABLE ENTITY

The request failed because the server was unable to process the contained instructions.

## 429 - TOO MANY REQUESTS

The request was [rate-limited](/reference/api/database-limits#rate-limits). [Implement retry logic with exponential backoff](/guides/production/error-handling#handle-rate-limits-429) to handle this error.

## 500 - UNKNOWN

An internal server error occurred. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) to handle transient errors.

## 502 - BAD GATEWAY

The API gateway received an invalid response from a backend service. This is typically a temporary error. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) to handle transient errors.

## 503 - UNAVAILABLE

The server is currently unavailable. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) to handle transient errors.

## 504 - GATEWAY TIMEOUT

The API gateway did not receive a timely response from the backend server. This can occur due to slow requests or backend processing delays. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) to handle transient errors.


# API reference
Source: https://docs.pinecone.io/reference/api/introduction

Pinecone API reference overview for Database, Inference, and Admin endpoints with supported SDKs including Python, Node.js, Java, and Go.

Pinecone's APIs let you interact programmatically with your Pinecone account.

<Note>
  [SDK versions](/reference/pinecone-sdks#sdk-versions) are pinned to specific API versions.
</Note>

## Database

Use the Database API to store and query records in [Pinecone Database](/guides/get-started/quickstart).

The following Pinecone SDKs support the Database API:

<CardGroup>
  <Card title="CLI" icon="terminal" href="/reference/cli/overview" />

  <Card title="Python SDK" icon="python" href="/reference/sdks/python/overview" />

  <Card title="Node.js SDK" icon="node-js" href="/reference/sdks/node/overview" />

  <Card title="Java SDK" icon="java" href="/reference/sdks/java/overview" />

  <Card title="Go SDK" icon="golang" href="/reference/sdks/go/overview" />
</CardGroup>

## Inference

Use the Inference API to generate vector embeddings and rerank results using [embedding models](/guides/index-data/create-an-index#embedding-models) and [reranking models](/guides/search/rerank-results#reranking-models) hosted on Pinecone's infrastructure.

There are two ways to use the Inference API:

* As a standalone service, through the [Rerank documents](/reference/api/latest/inference/rerank) and [Generate vectors](/reference/api/latest/inference/generate-embeddings) endpoints.
* As an integrated part of database operations, through the [Create an index with integrated embedding](/reference/api/latest/control-plane/create_for_model), [Upsert text](/reference/api/latest/data-plane/upsert_records), and [Search with text](/reference/api/latest/data-plane/search_records) endpoints.

The following Pinecone SDKs support using the Inference API:

<CardGroup>
  <Card title="Python SDK" icon="python" href="/reference/sdks/python/overview" />

  <Card title="Node.js SDK" icon="node-js" href="/reference/sdks/node/overview" />

  <Card title="Java SDK" icon="java" href="/reference/sdks/java/overview" />

  <Card title="Go SDK" icon="golang" href="/reference/sdks/go/overview" />
</CardGroup>


# Known limitations
Source: https://docs.pinecone.io/reference/api/known-limitations

Known limitations and feature restrictions for Pinecone indexes, including upsert consistency, metadata rules, and serverless caveats.

This page describes known limitations and feature restrictions in Pinecone.

## General

* [Upserts](/guides/index-data/upsert-data)
  * Pinecone is eventually consistent, so there can be a slight delay before upserted records are available to query.

    After upserting records, use the [`describe_index_stats`](/reference/api/2024-10/data-plane/describeindexstats) operation to check if the current vector count matches the number of records you expect, although this method may not work for pod-based indexes with multiple replicas.
  * Only indexes using the [dotproduct distance metric](/guides/index-data/indexing-overview#dotproduct) support querying sparse-dense vectors.

    Upserting, updating, and fetching sparse-dense vectors in indexes with a different distance metric will succeed, but querying will return an error.
  * Indexes created before February 22, 2023 do not support sparse vectors.
* [Metadata](/guides/index-data/upsert-data#upsert-with-metadata-filters)
  * Null metadata values aren't supported. Instead of setting a key to `null`, remove the key from the metadata payload.
  * Nested JSON objects are not supported.

## Serverless indexes

Serverless indexes do not support the following features:

* [Filtering index statistics by metadata](/reference/api/2024-10/data-plane/describeindexstats)
* [Private endpoints](/guides/production/configure-private-endpoints)

  * This feature is available on AWS only.


# API versioning
Source: https://docs.pinecone.io/reference/api/versioning

Pinecone REST API: Pinecone's APIs are versioned to ensure that your applications continue to work as expected as the platform evolves.

Pinecone's APIs are versioned to ensure that your applications continue to work as expected as the platform evolves. Versions are named by release date in the format `YYYY-MM`, for example, `2025-10`.

## Release schedule

On a quarterly basis, Pinecone releases a new **stable** API version as well as a **release candidate** of the next stable version.

* **Stable:** Each stable version remains unchanged and supported for a minimum of 12 months. Since stable versions are released every 3 months, this means you have at least 9 months to test and migrate your app to the newest stable version before support for the previous version is removed.

* **Release candidate:** The release candidate gives you insight into the upcoming changes in the next stable version. It is available for approximately 3 months before the release of the stable version and can include new features, improvements, and [breaking changes](#breaking-changes).

Below is an example of Pinecone's release schedule:

<img />

<img />

## Specify an API version

<Warning>
  When using the API directly, it is important to specify an API version in your requests. If you don't, requests default to the oldest supported stable version. Once support for that version ends, your requests will default to the next oldest stable version, which could include breaking changes that require you to update your integration.
</Warning>

To specify an API version, set the `X-Pinecone-Api-Version` header to the version name.

For example, to use the latest stable version (`2026-04`) to describe an index, set the `X-Pinecone-Api-Version` header:

```shell curl theme={null}
PINECONE_API_KEY="YOUR_API_KEY"

curl -i -X GET "https://api.pinecone.io/indexes/movie-recommendations" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2026-04"
```

To use an older version, specify that version instead.

## SDK versions

Official [Pinecone SDKs](/reference/pinecone-sdks) provide convenient access to Pinecone APIs. SDK versions are pinned to specific API versions. When a new API version is released, a new version of the SDK is also released.

For the mapping between SDK and API versions, see [SDK versions](/reference/pinecone-sdks#sdk-versions).

## Breaking changes

Breaking changes are changes that can potentially break your integration with a Pinecone API. Breaking changes include:

* Removing an entire operation
* Removing or renaming a parameter
* Removing or renaming a response field
* Adding a new required parameter
* Making a previously optional parameter required
* Changing the type of a parameter or response field
* Removing enum values
* Adding a new validation rule to an existing parameter
* Changing authentication or authorization requirements

## Non-breaking changes

Non-breaking changes are additive and should not break your integration. Additive changes include:

* Adding an operation
* Adding an optional parameter
* Adding an optional request header
* Adding a response field
* Adding a response header
* Adding enum values

## Get updates

To ensure you always know about upcoming API changes, follow the [Release notes](/release-notes/).


# Create an API key
Source: https://docs.pinecone.io/reference/api/2026-04/admin/create_api_key

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml post /admin/projects/{project_id}/api-keys
Create an API key for a project to authenticate Data Plane and Control Plane requests.


<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  const apiKey = await admin.apiKeys.create('YOUR_PROJECT_ID', {
    name: 'Example API Key',
    roles: ['ProjectEditor'],
  });

  // `apiKey.value` is returned only at creation time and cannot be retrieved
  // later. Store it securely and never log it.
  console.log(apiKey.key);
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "fmt"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      roles := []string{"ProjectEditor"}
      apiKey, err := adminClient.APIKey.Create(ctx, "YOUR_PROJECT_ID", &pinecone.CreateAPIKeyParams{
          Name:  "Example API Key",
          Roles: &roles,
      })
      if err != nil {
          log.Fatalf("Failed to create API key: %v", err)
      }
      // Value is returned only at creation time — store it securely and never log it
      fmt.Printf("Successfully created API key: %v\n", apiKey.Key.Id)
  }
  ```

  ```hcl Terraform theme={null}
  # Requires Terraform provider v4.0.0 or later
  resource "pinecone_api_key" "example" {
    name       = "Example API Key"
    project_id = "YOUR_PROJECT_ID"
    roles      = ["ProjectEditor"]
  }
  ```

  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
  PINECONE_PROJECT_ID="YOUR_PROJECT_ID"

  curl "https://api.pinecone.io/admin/projects/$PINECONE_PROJECT_ID/api-keys" \
  	-H "X-Pinecone-Api-Version: 2026-04" \
  	-H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
  	-d '{
  		"name": "Example API Key",
  		"roles": ["ProjectEditor"]
  	}'
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "key": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Example API key",
      "project_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "roles": [
        "ProjectEditor"
      ]
    },
    "value": "string"
  }
  ```
</ResponseExample>


# Invite a user to the organization
Source: https://docs.pinecone.io/reference/api/2026-04/admin/create_invite

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml post /admin/invites
Invite a user to the organization by email and grant their initial role bindings.


<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  const invite = await admin.invites.create({
    email: 'newhire@example.com',
    roleBindings: [
      { resourceType: 'organization', role: 'OrgMember' },
      {
        resourceType: 'project',
        resourceId: 'a2f7dddb-1597-4eff-9f71-535fde243f58',
        role: 'ProjectMember',
      },
    ],
  });
  console.log(invite);
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "fmt"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      projectId := "a2f7dddb-1597-4eff-9f71-535fde243f58"
      invite, err := adminClient.Invite.Create(ctx, &pinecone.CreateInviteParams{
          Email: "newhire@example.com",
          RoleBindings: []pinecone.RoleBindingInput{
              {ResourceType: pinecone.ResourceTypeOrganization, Role: "OrgMember"},
              {ResourceType: pinecone.ResourceTypeProject, ResourceId: &projectId, Role: "ProjectMember"},
          },
      })
      if err != nil {
          log.Fatalf("Failed to create invite: %v", err)
      }
      fmt.Printf("Invited %v (status: %v)\n", invite.Email, invite.Status)
  }
  ```

  ```hcl Terraform theme={null}
  # Requires Terraform provider v4.0.0 or later
  resource "pinecone_invite" "newhire" {
    email = "newhire@example.com"

    role_bindings = [
      {
        resource_type = "organization"
        role          = "OrgMember"
      },
      {
        resource_type = "project"
        resource_id   = "a2f7dddb-1597-4eff-9f71-535fde243f58"
        role          = "ProjectMember"
      }
    ]
  }
  ```

  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

  curl "https://api.pinecone.io/admin/invites" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "X-Pinecone-Api-Version: 2026-04" \
    -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
    -d '{
      "email": "newhire@example.com",
      "role_bindings": [
        {
          "resource_type": "organization",
          "role": "OrgMember"
        },
        {
          "resource_type": "project",
          "resource_id": "a2f7dddb-1597-4eff-9f71-535fde243f58",
          "role": "ProjectMember"
        }
      ]
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "id": "9c8e3528-b9c0-4358-84ce-84c28e91b566",
    "email": "newhire@example.com",
    "status": "pending",
    "expires_at": "2026-05-21T03:00:00Z",
    "processed_at": null,
    "created_at": "2026-04-14T20:00:00Z"
  }
  ```
</ResponseExample>


# Create a new project
Source: https://docs.pinecone.io/reference/api/2026-04/admin/create_project

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml post /admin/projects
Create a new project.

<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  const project = await admin.projects.create({ name: 'example-project' });
  console.log(project);
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "fmt"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      project, err := adminClient.Project.Create(ctx, &pinecone.CreateProjectParams{
          Name: "example-project",
      })
      if err != nil {
          log.Fatalf("Failed to create project: %v", err)
      }
      fmt.Printf("Successfully created project: %v\n", project.Id)
  }
  ```

  ```hcl Terraform theme={null}
  # Requires Terraform provider v4.0.0 or later
  resource "pinecone_project" "example" {
    name = "example-project"
  }
  ```

  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

  curl "https://api.pinecone.io/admin/projects" \
      -H "X-Pinecone-Api-Version: 2026-04" \
  	-H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
  	-d '{
          "name":"example-project"
          }'
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "example-project",
    "max_pods": 0,
    "force_encryption_with_cmek": false,
    "organization_id": "string",
    "created_at": "2025-03-16T22:46:45.030Z"
  }
  ```
</ResponseExample>


# Create a role binding
Source: https://docs.pinecone.io/reference/api/2026-04/admin/create_role_binding

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml post /admin/role-bindings
Grant a role to a principal at an organization or project scope.


<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  const roleBinding = await admin.roleBindings.create({
    principalType: 'service_account',
    principalId: 'f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c',
    resourceType: 'project',
    resourceId: 'a2f7dddb-1597-4eff-9f71-535fde243f58',
    role: 'DataPlaneEditor',
  });
  console.log(roleBinding);
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "fmt"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      projectId := "a2f7dddb-1597-4eff-9f71-535fde243f58"
      roleBinding, err := adminClient.RoleBinding.Create(ctx, &pinecone.CreateRoleBindingParams{
          PrincipalType: pinecone.PrincipalTypeServiceAccount,
          PrincipalId:   "f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
          ResourceType:  pinecone.ResourceTypeProject,
          ResourceId:    &projectId,
          Role:          "DataPlaneEditor",
      })
      if err != nil {
          log.Fatalf("Failed to create role binding: %v", err)
      }
      fmt.Printf("Successfully created role binding: %v\n", roleBinding.Id)
  }
  ```

  ```hcl Terraform theme={null}
  # Requires Terraform provider v4.0.0 or later
  # Bindings are immutable; changing any attribute forces replacement
  resource "pinecone_role_binding" "ci_data_plane_editor" {
    principal_type = "service_account"
    principal_id   = "f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c"
    resource_type  = "project"
    resource_id    = "a2f7dddb-1597-4eff-9f71-535fde243f58"
    role           = "DataPlaneEditor"
  }
  ```

  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

  curl "https://api.pinecone.io/admin/role-bindings" \
  	-H "X-Pinecone-Api-Version: 2026-04" \
  	-H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
  	-d '{
  		"principal_type": "service_account",
  		"principal_id": "f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
  		"resource_type": "project",
  		"resource_id": "a2f7dddb-1597-4eff-9f71-535fde243f58",
  		"role": "DataPlaneEditor"
  	}'
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "id": "9a8e3528-b9c0-4358-84ce-84c28e91b566",
    "principal_type": "service_account",
    "principal_id": "f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
    "resource_type": "project",
    "resource_id": "a2f7dddb-1597-4eff-9f71-535fde243f58",
    "role": "DataPlaneEditor",
    "created_at": "2026-04-10T15:23:00Z"
  }
  ```
</ResponseExample>


# Create a service account
Source: https://docs.pinecone.io/reference/api/2026-04/admin/create_service_account

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml post /admin/service-accounts
Create a service account with optional initial role bindings; the client secret is returned only once.


<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  // `clientSecret` is returned only once and cannot be retrieved later
  const { serviceAccount, clientSecret } = await admin.serviceAccounts.create({
    name: 'ci-prod',
    roleBindings: [
      {
        resourceType: 'project',
        resourceId: 'a2f7dddb-1597-4eff-9f71-535fde243f58',
        role: 'DataPlaneEditor',
      },
    ],
  });
  console.log(serviceAccount);
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "fmt"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      projectId := "a2f7dddb-1597-4eff-9f71-535fde243f58"
      sa, err := adminClient.ServiceAccount.Create(ctx, &pinecone.CreateServiceAccountParams{
          Name: "ci-prod",
          RoleBindings: []pinecone.RoleBindingInput{
              {
                  ResourceType: pinecone.ResourceTypeProject,
                  ResourceId:   &projectId,
                  Role:         "DataPlaneEditor",
              },
          },
      })
      if err != nil {
          log.Fatalf("Failed to create service account: %v", err)
      }
      // ClientSecret is returned only once — store it securely and never log it
      fmt.Printf("Successfully created service account: %v\n", sa.ServiceAccount.Id)
  }
  ```

  ```hcl Terraform theme={null}
  # Requires Terraform provider v4.0.0 or later
  # Roles are assigned with separate pinecone_role_binding resources
  resource "pinecone_service_account" "ci_prod" {
    name = "ci-prod"
  }

  resource "pinecone_role_binding" "ci_prod_data_plane_editor" {
    principal_id   = pinecone_service_account.ci_prod.id
    principal_type = "service_account"
    resource_type  = "project"
    resource_id    = "a2f7dddb-1597-4eff-9f71-535fde243f58"
    role           = "DataPlaneEditor"
  }

  output "ci_prod_client_secret" {
    value     = pinecone_service_account.ci_prod.client_secret
    sensitive = true
  }
  ```

  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

  curl "https://api.pinecone.io/admin/service-accounts" \
  	-H "X-Pinecone-Api-Version: 2026-04" \
  	-H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
  	-d '{
  		"name": "ci-prod",
  		"role_bindings": [
  			{
  				"resource_type": "project",
  				"resource_id": "a2f7dddb-1597-4eff-9f71-535fde243f58",
  				"role": "DataPlaneEditor"
  			}
  		]
  	}'
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "service_account": {
      "id": "f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
      "name": "ci-prod",
      "client_id": "l3Ow0CmFyc4jOONcwiKUCRqQKN0tiCAn",
      "created_at": "2026-04-10T15:23:00Z",
      "updated_at": "2026-04-10T15:23:00Z"
    },
    "client_secret": "8p-kkC23XOWvkCosKq-BOn3G74qp__rBcDMxc82iB4gfzRvuhSCRBKM7C5Q7TAzj"
  }
  ```
</ResponseExample>


# Delete an API key
Source: https://docs.pinecone.io/reference/api/2026-04/admin/delete_api_key

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml delete /admin/api-keys/{api_key_id}
Delete an API key from a project.

<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  await admin.apiKeys.delete('YOUR_API_KEY_ID');
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      if err := adminClient.APIKey.Delete(ctx, "YOUR_API_KEY_ID"); err != nil {
          log.Fatalf("Failed to delete API key: %v", err)
      }
  }
  ```

  ```hcl Terraform theme={null}
  # Requires Terraform provider v4.0.0 or later
  # This block defines the API key. To delete it, either remove the block and run
  # `terraform apply`, or run:
  #   terraform destroy -target=pinecone_api_key.example
  resource "pinecone_api_key" "example" {
    name       = "Example API Key"
    project_id = "YOUR_PROJECT_ID"
  }
  ```

  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
  PINECONE_API_KEY_ID="YOUR_KEY_ID"

  curl -X DELETE "https://api.pinecone.io/admin/api-keys/$PINECONE_API_KEY_ID" \
  	-H "X-Pinecone-Api-Version: 2026-04" \
  	-H "Authorization: Bearer $PINECONE_ACCESS_TOKEN"
  ```
</RequestExample>


# Delete an invite
Source: https://docs.pinecone.io/reference/api/2026-04/admin/delete_invite

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml delete /admin/invites/{invite_id}
Delete a pending or expired invite and its role bindings; to remove an accepted user, delete the user instead.


<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  await admin.invites.delete('YOUR_INVITE_ID');
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      if err := adminClient.Invite.Delete(ctx, "YOUR_INVITE_ID"); err != nil {
          log.Fatalf("Failed to delete invite: %v", err)
      }
  }
  ```

  ```hcl Terraform theme={null}
  # Requires Terraform provider v4.0.0 or later
  # This block defines the invite. To revoke a pending invite, either remove the
  # block and run `terraform apply`, or run:
  #   terraform destroy -target=pinecone_invite.newhire
  resource "pinecone_invite" "newhire" {
    email = "newhire@example.com"

    role_bindings = [
      {
        resource_type = "organization"
        role          = "OrgMember"
      }
    ]
  }
  ```

  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
  PINECONE_INVITE_ID="YOUR_INVITE_ID"

  curl -X DELETE "https://api.pinecone.io/admin/invites/$PINECONE_INVITE_ID" \
  	-H "X-Pinecone-Api-Version: 2026-04" \
  	-H "Authorization: Bearer $PINECONE_ACCESS_TOKEN"
  ```
</RequestExample>


# Delete a project
Source: https://docs.pinecone.io/reference/api/2026-04/admin/delete_project

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml delete /admin/projects/{project_id}
Delete a project and all its configuration; delete its indexes, assistants, backups, and collections first.


<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  await admin.projects.delete('YOUR_PROJECT_ID');
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      if err := adminClient.Project.Delete(ctx, "YOUR_PROJECT_ID"); err != nil {
          log.Fatalf("Failed to delete project: %v", err)
      }
  }
  ```

  ```hcl Terraform theme={null}
  # Requires Terraform provider v4.0.0 or later
  # This block defines the project. To delete it, either remove the block and run
  # `terraform apply`, or run:
  #   terraform destroy -target=pinecone_project.example
  resource "pinecone_project" "example" {
    name = "example-project"
  }
  ```

  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
  PROJECT_ID="YOUR_PROJECT_ID"

  curl -X DELETE "https://api.pinecone.io/admin/projects/$PROJECT_ID" \
  	-H "X-Pinecone-Api-Version: 2026-04" \
  	-H "Authorization: Bearer $PINECONE_ACCESS_TOKEN"
  ```
</RequestExample>


# Delete a role binding
Source: https://docs.pinecone.io/reference/api/2026-04/admin/delete_role_binding

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml delete /admin/role-bindings/{role_binding_id}
Delete a role binding; permissions are revoked when the deletion completes.


<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  await admin.roleBindings.delete('YOUR_ROLE_BINDING_ID');
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      if err := adminClient.RoleBinding.Delete(ctx, "YOUR_ROLE_BINDING_ID"); err != nil {
          log.Fatalf("Failed to delete role binding: %v", err)
      }
  }
  ```

  ```hcl Terraform theme={null}
  # Requires Terraform provider v4.0.0 or later
  # This block defines the role binding. To revoke the role, either remove the
  # block and run `terraform apply`, or run:
  #   terraform destroy -target=pinecone_role_binding.ci_data_plane_editor
  resource "pinecone_role_binding" "ci_data_plane_editor" {
    principal_type = "service_account"
    principal_id   = "f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c"
    resource_type  = "project"
    resource_id    = "a2f7dddb-1597-4eff-9f71-535fde243f58"
    role           = "DataPlaneEditor"
  }
  ```

  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
  PINECONE_ROLE_BINDING_ID="YOUR_ROLE_BINDING_ID"

  curl -X DELETE "https://api.pinecone.io/admin/role-bindings/$PINECONE_ROLE_BINDING_ID" \
  	-H "X-Pinecone-Api-Version: 2026-04" \
  	-H "Authorization: Bearer $PINECONE_ACCESS_TOKEN"
  ```
</RequestExample>


# Delete a service account
Source: https://docs.pinecone.io/reference/api/2026-04/admin/delete_service_account

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml delete /admin/service-accounts/{service_account_id}
Delete a service account and its role bindings; tokens it minted are revoked within a few seconds.


<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  await admin.serviceAccounts.delete('YOUR_SERVICE_ACCOUNT_ID');
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      if err := adminClient.ServiceAccount.Delete(ctx, "YOUR_SERVICE_ACCOUNT_ID"); err != nil {
          log.Fatalf("Failed to delete service account: %v", err)
      }
  }
  ```

  ```hcl Terraform theme={null}
  # Requires Terraform provider v4.0.0 or later
  # This block defines the service account. To delete it, either remove the block
  # and run `terraform apply`, or run:
  #   terraform destroy -target=pinecone_service_account.ci_prod
  resource "pinecone_service_account" "ci_prod" {
    name = "ci-prod"
  }
  ```

  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
  PINECONE_SERVICE_ACCOUNT_ID="YOUR_SERVICE_ACCOUNT_ID"

  curl -X DELETE "https://api.pinecone.io/admin/service-accounts/$PINECONE_SERVICE_ACCOUNT_ID" \
  	-H "X-Pinecone-Api-Version: 2026-04" \
  	-H "Authorization: Bearer $PINECONE_ACCESS_TOKEN"
  ```
</RequestExample>


# Remove a user from the organization
Source: https://docs.pinecone.io/reference/api/2026-04/admin/delete_user

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml delete /admin/users/{user_id}
Remove a user from the organization and revoke their role bindings; their Pinecone account is not deleted.


<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  await admin.users.delete('YOUR_USER_ID');
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      if err := adminClient.User.Delete(ctx, "YOUR_USER_ID"); err != nil {
          log.Fatalf("Failed to delete user: %v", err)
      }
  }
  ```

  ```hcl Terraform theme={null}
  # Requires Terraform provider v4.0.0 or later
  # Users join by accepting an invite, so import the existing member first:
  #   terraform import pinecone_user.teammate YOUR_USER_ID
  # Then remove the resource block and run `terraform apply` to remove them
  # from the organization.
  resource "pinecone_user" "teammate" {
    id = "YOUR_USER_ID"
  }
  ```

  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
  PINECONE_USER_ID="YOUR_USER_ID"

  curl -X DELETE "https://api.pinecone.io/admin/users/$PINECONE_USER_ID" \
  	-H "X-Pinecone-Api-Version: 2026-04" \
  	-H "Authorization: Bearer $PINECONE_ACCESS_TOKEN"
  ```
</RequestExample>


# Get API key details
Source: https://docs.pinecone.io/reference/api/2026-04/admin/fetch_api_key

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml get /admin/api-keys/{api_key_id}
Get an API key's details, excluding its secret.

<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  const apiKey = await admin.apiKeys.describe('YOUR_API_KEY_ID');
  console.log(apiKey);
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "fmt"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      apiKey, err := adminClient.APIKey.Describe(ctx, "YOUR_API_KEY_ID")
      if err != nil {
          log.Fatalf("Failed to describe API key: %v", err)
      }
      fmt.Printf("API key: %v (%v)\n", apiKey.Name, apiKey.Id)
  }
  ```

  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
  PINECONE_API_KEY_ID="3fa85f64-5717-4562-b3fc-2c963f66afa6"

  curl -X GET "https://api.pinecone.io/admin/api-keys/$PINECONE_API_KEY_ID" \
  	-H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
      -H "accept: application/json" \
      -H "X-Pinecone-Api-Version: 2026-04"
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "string",
    "project_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "roles": [
      "ProjectEditor"
    ]
  }
  ```
</ResponseExample>


# Get invite details
Source: https://docs.pinecone.io/reference/api/2026-04/admin/fetch_invite

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml get /admin/invites/{invite_id}
Get an invite in the caller's organization by ID.

<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  const invite = await admin.invites.describe('YOUR_INVITE_ID');
  console.log(invite);
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "fmt"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      invite, err := adminClient.Invite.Describe(ctx, "YOUR_INVITE_ID")
      if err != nil {
          log.Fatalf("Failed to describe invite: %v", err)
      }
      fmt.Printf("Invite: %v (status: %v)\n", invite.Email, invite.Status)
  }
  ```

  ```hcl Terraform theme={null}
  # Requires Terraform provider v4.0.0 or later
  data "pinecone_invite" "example" {
    id = "YOUR_INVITE_ID"
  }

  output "invite_status" {
    value = data.pinecone_invite.example.status
  }
  ```

  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
  PINECONE_INVITE_ID="9c8e3528-b9c0-4358-84ce-84c28e91b566"

  curl -X GET "https://api.pinecone.io/admin/invites/$PINECONE_INVITE_ID" \
  	-H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
  	-H "accept: application/json" \
  	-H "X-Pinecone-Api-Version: 2026-04"
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "id": "9c8e3528-b9c0-4358-84ce-84c28e91b566",
    "email": "newhire@example.com",
    "status": "pending",
    "expires_at": "2026-05-21T03:00:00Z",
    "processed_at": null,
    "created_at": "2026-04-14T20:00:00Z"
  }
  ```
</ResponseExample>


# Get project details
Source: https://docs.pinecone.io/reference/api/2026-04/admin/fetch_project

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml get /admin/projects/{project_id}
Get a project's details.

<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  const project = await admin.projects.describe('YOUR_PROJECT_ID');
  console.log(project);
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "fmt"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      project, err := adminClient.Project.Describe(ctx, "YOUR_PROJECT_ID")
      if err != nil {
          log.Fatalf("Failed to describe project: %v", err)
      }
      fmt.Printf("Project: %v (%v)\n", project.Name, project.Id)
  }
  ```

  ```hcl Terraform theme={null}
  # Requires Terraform provider v4.0.0 or later
  data "pinecone_project" "example" {
    id = "YOUR_PROJECT_ID"
  }

  output "project_name" {
    value = data.pinecone_project.example.name
  }
  ```

  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
  PROJECT_ID="3fa85f64-5717-4562-b3fc-2c963f66afa6"

  curl -X GET "https://api.pinecone.io/admin/projects/$PROJECT_ID" \
      -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
  	-H "X-Pinecone-Api-Version: 2026-04" \
      -H "accept: application/json"
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "example-project",
    "max_pods": 0,
    "force_encryption_with_cmek": false,
    "organization_id": "string",
    "created_at": "2025-03-17T00:30:23.262Z"
  }
  ```
</ResponseExample>


# Get role binding details
Source: https://docs.pinecone.io/reference/api/2026-04/admin/fetch_role_binding

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml get /admin/role-bindings/{role_binding_id}
Get a role binding in the caller's organization by ID.


<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  const roleBinding = await admin.roleBindings.describe('YOUR_ROLE_BINDING_ID');
  console.log(roleBinding);
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "fmt"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      roleBinding, err := adminClient.RoleBinding.Describe(ctx, "YOUR_ROLE_BINDING_ID")
      if err != nil {
          log.Fatalf("Failed to describe role binding: %v", err)
      }
      fmt.Printf("Role binding: %v (%v)\n", roleBinding.Role, roleBinding.Id)
  }
  ```

  ```hcl Terraform theme={null}
  # Requires Terraform provider v4.0.0 or later
  data "pinecone_role_binding" "example" {
    id = "YOUR_ROLE_BINDING_ID"
  }

  output "role" {
    value = data.pinecone_role_binding.example.role
  }
  ```

  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
  PINECONE_ROLE_BINDING_ID="9a8e3528-b9c0-4358-84ce-84c28e91b566"

  curl -X GET "https://api.pinecone.io/admin/role-bindings/$PINECONE_ROLE_BINDING_ID" \
  	-H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
  	-H "accept: application/json" \
  	-H "X-Pinecone-Api-Version: 2026-04"
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "id": "9a8e3528-b9c0-4358-84ce-84c28e91b566",
    "principal_type": "service_account",
    "principal_id": "f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
    "resource_type": "project",
    "resource_id": "a2f7dddb-1597-4eff-9f71-535fde243f58",
    "role": "DataPlaneEditor",
    "created_at": "2026-04-10T15:23:00Z"
  }
  ```
</ResponseExample>


# Get service account details
Source: https://docs.pinecone.io/reference/api/2026-04/admin/fetch_service_account

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml get /admin/service-accounts/{service_account_id}
Get a service account by ID; the client secret is returned only from create and rotate-secret requests.


<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  const serviceAccount = await admin.serviceAccounts.describe('YOUR_SERVICE_ACCOUNT_ID');
  console.log(serviceAccount);
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "fmt"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      sa, err := adminClient.ServiceAccount.Describe(ctx, "YOUR_SERVICE_ACCOUNT_ID")
      if err != nil {
          log.Fatalf("Failed to describe service account: %v", err)
      }
      fmt.Printf("Service account: %v (%v)\n", sa.Name, sa.Id)
  }
  ```

  ```hcl Terraform theme={null}
  # Requires Terraform provider v4.0.0 or later
  data "pinecone_service_account" "example" {
    id = "YOUR_SERVICE_ACCOUNT_ID"
  }

  output "service_account_name" {
    value = data.pinecone_service_account.example.name
  }
  ```

  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
  PINECONE_SERVICE_ACCOUNT_ID="f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c"

  curl -X GET "https://api.pinecone.io/admin/service-accounts/$PINECONE_SERVICE_ACCOUNT_ID" \
  	-H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
  	-H "accept: application/json" \
  	-H "X-Pinecone-Api-Version: 2026-04"
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "id": "f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
    "name": "My Service Account",
    "client_id": "l3Ow0CmFyc4jOONcwiKUCRqQKN0tiCAn",
    "created_at": "2026-04-10T15:23:00Z",
    "updated_at": "2026-04-12T09:11:00Z"
  }
  ```
</ResponseExample>


# Get user details
Source: https://docs.pinecone.io/reference/api/2026-04/admin/fetch_user

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml get /admin/users/{user_id}
Get a user in the caller's organization by ID.

<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  const user = await admin.users.describe('YOUR_USER_ID');
  console.log(user);
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "fmt"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      user, err := adminClient.User.Describe(ctx, "YOUR_USER_ID")
      if err != nil {
          log.Fatalf("Failed to describe user: %v", err)
      }
      fmt.Printf("User: %v (%v)\n", user.Email, user.Id)
  }
  ```

  ```hcl Terraform theme={null}
  # Requires Terraform provider v4.0.0 or later
  # Look up a user by id or by email
  data "pinecone_user" "example" {
    id = "YOUR_USER_ID"
  }

  output "user_name" {
    value = data.pinecone_user.example.name
  }
  ```

  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
  PINECONE_USER_ID="e2e92523-85dc-4142-b8c2-e681be8b78df"

  curl -X GET "https://api.pinecone.io/admin/users/$PINECONE_USER_ID" \
  	-H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
  	-H "accept: application/json" \
  	-H "X-Pinecone-Api-Version: 2026-04"
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "id": "e2e92523-85dc-4142-b8c2-e681be8b78df",
    "email": "alice@example.com",
    "name": "Alice Example",
    "created_at": "2026-04-10T15:23:00Z",
    "updated_at": "2026-04-12T09:11:00Z"
  }
  ```
</ResponseExample>


# Create an access token
Source: https://docs.pinecone.io/reference/api/2026-04/admin/get_token

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/oauth_2026-04.oas.yaml post /oauth/token
Obtain an access token for a service account using the OAuth2 client credentials flow. An access token is needed to authorize requests to the Pinecone Admin API.
The host domain for OAuth endpoints is `login.pinecone.io`.


<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // You don't call this endpoint directly when using the SDK. The AdminClient
  // exchanges your service account credentials for an access token on the first
  // admin request and reuses it for subsequent calls.
  const admin = new AdminClient({
    clientId: 'YOUR_CLIENT_ID',
    clientSecret: 'YOUR_CLIENT_SECRET',
  });

  const { data: projects } = await admin.projects.list();
  console.log(projects);
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "fmt"
      "log"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      // You don't call this endpoint directly when using the SDK. The AdminClient
      // exchanges your service account credentials for an access token.
      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     "YOUR_CLIENT_ID",
          ClientSecret: "YOUR_CLIENT_SECRET",
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      projects, err := adminClient.Project.List(ctx)
      if err != nil {
          log.Fatalf("Failed to list projects: %v", err)
      }
      fmt.Printf("Found %v projects\n", len(projects))
  }
  ```

  ```bash curl theme={null}
  curl "https://login.pinecone.io/oauth/token" \ # Note: Base URL is login.pinecone.io
  	-H "X-Pinecone-Api-Version: 2026-04" \
  	-H "Content-Type: application/json" \
  	-d '{
  		"grant_type": "client_credentials",
  		"client_id": "YOUR_CLIENT_ID",
  		"client_secret": "YOUR_CLIENT_SECRET",
  		"audience": "https://api.pinecone.io/"
  	}'
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
      "access_token":"YOUR_ACCESS_TOKEN",
      "expires_in":86400,
      "token_type":"Bearer"
  }
  ```
</ResponseExample>


# List API keys
Source: https://docs.pinecone.io/reference/api/2026-04/admin/list_api_keys

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml get /admin/projects/{project_id}/api-keys
List all API keys in a project.

<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  const { data: apiKeys } = await admin.apiKeys.list('YOUR_PROJECT_ID');
  console.log(apiKeys);
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "fmt"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      apiKeys, err := adminClient.APIKey.List(ctx, "YOUR_PROJECT_ID")
      if err != nil {
          log.Fatalf("Failed to list API keys: %v", err)
      }
      for _, apiKey := range apiKeys {
          fmt.Printf("API key: %v (%v)\n", apiKey.Name, apiKey.Id)
      }
  }
  ```

  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
  PINECONE_PROJECT_ID="YOUR_PROJECT_ID"

  curl -X GET "https://api.pinecone.io/admin/projects/$PINECONE_PROJECT_ID/api-keys" \
      -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
      -H "X-Pinecone-Api-Version: 2026-04"
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "data": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "name": "string",
        "project_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "roles": [
          "ProjectEditor"
        ]
      }
    ]
  }
  ```
</ResponseExample>


# List invites
Source: https://docs.pinecone.io/reference/api/2026-04/admin/list_invites

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml get /admin/invites
List pending and expired invites in the caller's organization.

<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  const { data: invites } = await admin.invites.list();
  console.log(invites);
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "fmt"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      invites, err := adminClient.Invite.List(ctx, &pinecone.ListInvitesParams{})
      if err != nil {
          log.Fatalf("Failed to list invites: %v", err)
      }
      for _, invite := range invites.Data {
          fmt.Printf("Invite: %v (status: %v)\n", invite.Email, invite.Status)
      }
  }
  ```

  ```hcl Terraform theme={null}
  # Requires Terraform provider v4.0.0 or later
  data "pinecone_invites" "all" {}

  output "invite_emails" {
    value = [for invite in data.pinecone_invites.all.invites : invite.email]
  }
  ```

  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

  curl -X GET "https://api.pinecone.io/admin/invites" \
  	-H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
  	-H "accept: application/json" \
  	-H "X-Pinecone-Api-Version: 2026-04"
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "data": [
      {
        "id": "9c8e3528-b9c0-4358-84ce-84c28e91b566",
        "email": "newhire@example.com",
        "status": "pending",
        "expires_at": "2026-05-21T03:00:00Z",
        "processed_at": null,
        "created_at": "2026-04-14T20:00:00Z"
      }
    ],
    "pagination": {
      "next": "eyJsYXN0X2lkIjoiOWM4ZTM1MjgifQ=="
    }
  }
  ```
</ResponseExample>


# List projects
Source: https://docs.pinecone.io/reference/api/2026-04/admin/list_projects

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml get /admin/projects
List all projects in an organization.

<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  const { data: projects } = await admin.projects.list();
  console.log(projects);
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "fmt"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      projects, err := adminClient.Project.List(ctx)
      if err != nil {
          log.Fatalf("Failed to list projects: %v", err)
      }
      for _, project := range projects {
          fmt.Printf("Project: %v (%v)\n", project.Name, project.Id)
      }
  }
  ```

  ```hcl Terraform theme={null}
  # Requires Terraform provider v4.0.0 or later
  data "pinecone_projects" "all" {}

  output "project_names" {
    value = [for project in data.pinecone_projects.all.projects : project.name]
  }
  ```

  ```bash curl theme={null}
  curl -X GET "https://api.pinecone.io/admin/projects" \
      -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
      -H "X-Pinecone-Api-Version: 2026-04"
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "data": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "name": "example-project",
        "max_pods": 0,
        "force_encryption_with_cmek": true,
        "organization_id": "<string>",
        "created_at": "2023-11-07T05:31:56Z"
      }
    ]
  }
  ```
</ResponseExample>


# List role bindings
Source: https://docs.pinecone.io/reference/api/2026-04/admin/list_role_bindings

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml get /admin/role-bindings
List role bindings in the caller's organization, optionally filtered by principal, resource, and role.


<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  const { data: roleBindings } = await admin.roleBindings.list({
    principalType: 'user',
    principalId: 'e2e92523-85dc-4142-b8c2-e681be8b78df',
  });
  console.log(roleBindings);
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "fmt"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      principalType := pinecone.PrincipalTypeUser
      principalId := "e2e92523-85dc-4142-b8c2-e681be8b78df"
      roleBindings, err := adminClient.RoleBinding.List(ctx, &pinecone.ListRoleBindingsParams{
          PrincipalType: &principalType,
          PrincipalId:   &principalId,
      })
      if err != nil {
          log.Fatalf("Failed to list role bindings: %v", err)
      }
      for _, roleBinding := range roleBindings.Data {
          fmt.Printf("Role binding: %v (%v)\n", roleBinding.Role, roleBinding.Id)
      }
  }
  ```

  ```hcl Terraform theme={null}
  # Requires Terraform provider v4.0.0 or later
  data "pinecone_role_bindings" "user_roles" {
    principal_type = "user"
    principal_id   = "e2e92523-85dc-4142-b8c2-e681be8b78df"
  }

  output "user_roles" {
    value = [for b in data.pinecone_role_bindings.user_roles.role_bindings : b.role]
  }
  ```

  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

  curl -X GET "https://api.pinecone.io/admin/role-bindings?principal_type=user&principal_id=e2e92523-85dc-4142-b8c2-e681be8b78df" \
  	-H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
  	-H "accept: application/json" \
  	-H "X-Pinecone-Api-Version: 2026-04"
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "data": [
      {
        "id": "5a86ed21-daf1-448d-a9ca-f92a0fd839d3",
        "principal_type": "user",
        "principal_id": "e2e92523-85dc-4142-b8c2-e681be8b78df",
        "resource_type": "organization",
        "resource_id": "-ExampleOrgId0000000",
        "role": "OrgMember",
        "created_at": "2026-04-10T15:23:00Z"
      }
    ],
    "pagination": {
      "next": "eyJsYXN0X2lkIjoiNWE4NmVkMjEifQ=="
    }
  }
  ```
</ResponseExample>


# List service accounts
Source: https://docs.pinecone.io/reference/api/2026-04/admin/list_service_accounts

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml get /admin/service-accounts
List service accounts in the caller's organization.

<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  const { data: serviceAccounts } = await admin.serviceAccounts.list();
  console.log(serviceAccounts);
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "fmt"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      serviceAccounts, err := adminClient.ServiceAccount.List(ctx, &pinecone.ListServiceAccountsParams{})
      if err != nil {
          log.Fatalf("Failed to list service accounts: %v", err)
      }
      for _, sa := range serviceAccounts.Data {
          fmt.Printf("Service account: %v (%v)\n", sa.Name, sa.Id)
      }
  }
  ```

  ```hcl Terraform theme={null}
  # Requires Terraform provider v4.0.0 or later
  data "pinecone_service_accounts" "all" {}

  output "service_account_names" {
    value = [for sa in data.pinecone_service_accounts.all.service_accounts : sa.name]
  }
  ```

  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

  curl -X GET "https://api.pinecone.io/admin/service-accounts" \
  	-H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
  	-H "accept: application/json" \
  	-H "X-Pinecone-Api-Version: 2026-04"
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "data": [
      {
        "id": "f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
        "name": "My Service Account",
        "client_id": "l3Ow0CmFyc4jOONcwiKUCRqQKN0tiCAn",
        "created_at": "2026-04-10T15:23:00Z",
        "updated_at": "2026-04-12T09:11:00Z"
      }
    ],
    "pagination": {
      "next": "eyJsYXN0X2lkIjoiZDI0MTc3YTAifQ=="
    }
  }
  ```
</ResponseExample>


# List users in the organization
Source: https://docs.pinecone.io/reference/api/2026-04/admin/list_users

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml get /admin/users
List users in the caller's organization, optionally filtered by email address.


<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  const { data: users } = await admin.users.list();
  console.log(users);
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "fmt"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      users, err := adminClient.User.List(ctx, &pinecone.ListUsersParams{})
      if err != nil {
          log.Fatalf("Failed to list users: %v", err)
      }
      for _, user := range users.Data {
          fmt.Printf("User: %v (%v)\n", user.Email, user.Id)
      }
  }
  ```

  ```hcl Terraform theme={null}
  # Requires Terraform provider v4.0.0 or later
  data "pinecone_users" "all" {}

  output "user_emails" {
    value = [for user in data.pinecone_users.all.users : user.email]
  }
  ```

  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

  curl -X GET "https://api.pinecone.io/admin/users" \
  	-H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
  	-H "accept: application/json" \
  	-H "X-Pinecone-Api-Version: 2026-04"
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "data": [
      {
        "id": "e2e92523-85dc-4142-b8c2-e681be8b78df",
        "email": "alice@example.com",
        "name": "Alice Example",
        "created_at": "2026-04-10T15:23:00Z",
        "updated_at": "2026-04-12T09:11:00Z"
      }
    ],
    "pagination": {
      "next": "eyJsYXN0X2lkIjoiZTJlOTI1MjMifQ=="
    }
  }
  ```
</ResponseExample>


# Resend an invite email
Source: https://docs.pinecone.io/reference/api/2026-04/admin/resend_invite

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml post /admin/invites/{invite_id}/resend
Resend the invite email and extend its expiration to 7 days from now; limited to 100 emails per hour per organization.


<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  const invite = await admin.invites.resend('YOUR_INVITE_ID');
  console.log(invite);
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "fmt"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      invite, err := adminClient.Invite.Resend(ctx, "YOUR_INVITE_ID")
      if err != nil {
          log.Fatalf("Failed to resend invite: %v", err)
      }
      fmt.Printf("Resent invite to %v (status: %v)\n", invite.Email, invite.Status)
  }
  ```

  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
  PINECONE_INVITE_ID="9c8e3528-b9c0-4358-84ce-84c28e91b566"

  curl -X POST "https://api.pinecone.io/admin/invites/$PINECONE_INVITE_ID/resend" \
  	-H "X-Pinecone-Api-Version: 2026-04" \
  	-H "Authorization: Bearer $PINECONE_ACCESS_TOKEN"
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "id": "9c8e3528-b9c0-4358-84ce-84c28e91b566",
    "email": "newhire@example.com",
    "status": "pending",
    "expires_at": "2026-05-28T20:14:00Z",
    "processed_at": null,
    "created_at": "2026-04-14T20:00:00Z"
  }
  ```
</ResponseExample>


# Rotate a service account's OAuth client secret
Source: https://docs.pinecone.io/reference/api/2026-04/admin/rotate_service_account_secret

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml post /admin/service-accounts/{service_account_id}/rotate-secret
Rotate a service account's OAuth client secret; the previous secret and its tokens are revoked within seconds and the new secret is returned only once.


<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  // The previous secret is invalidated, and the new one is returned only once
  const { serviceAccount, clientSecret } = await admin.serviceAccounts.rotateSecret(
    'YOUR_SERVICE_ACCOUNT_ID'
  );
  console.log(serviceAccount);
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "fmt"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      sa, err := adminClient.ServiceAccount.RotateSecret(ctx, "YOUR_SERVICE_ACCOUNT_ID")
      if err != nil {
          log.Fatalf("Failed to rotate service account secret: %v", err)
      }
      // ClientSecret is returned only once — store it securely and never log it
      fmt.Printf("Successfully rotated secret for service account: %v\n", sa.ServiceAccount.Id)
  }
  ```

  ```hcl Terraform theme={null}
  # Requires Terraform provider v4.0.0 or later
  # Change rotate_trigger to any new value to issue and store a new secret
  resource "pinecone_service_account" "ci_prod" {
    name           = "ci-prod"
    rotate_trigger = "2026-04-10"
  }
  ```

  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
  PINECONE_SERVICE_ACCOUNT_ID="f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c"

  curl -X POST "https://api.pinecone.io/admin/service-accounts/$PINECONE_SERVICE_ACCOUNT_ID/rotate-secret" \
  	-H "X-Pinecone-Api-Version: 2026-04" \
  	-H "Authorization: Bearer $PINECONE_ACCESS_TOKEN"
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "service_account": {
      "id": "f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
      "name": "My Service Account",
      "client_id": "l3Ow0CmFyc4jOONcwiKUCRqQKN0tiCAn",
      "created_at": "2026-04-10T15:23:00Z",
      "updated_at": "2026-04-10T15:23:00Z"
    },
    "client_secret": "8p-kkC23XOWvkCosKq-BOn3G74qp__rBcDMxc82iB4gfzRvuhSCRBKM7C5Q7TAzj"
  }
  ```
</ResponseExample>


# Update an API key
Source: https://docs.pinecone.io/reference/api/2026-04/admin/update_api_key

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml patch /admin/api-keys/{api_key_id}
Update an API key's name and roles.

<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  const apiKey = await admin.apiKeys.update('YOUR_API_KEY_ID', {
    name: 'New API key name',
    roles: ['ProjectEditor'],
  });
  console.log(apiKey);
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "fmt"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      name := "New API key name"
      roles := []string{"ProjectEditor"}
      apiKey, err := adminClient.APIKey.Update(ctx, "YOUR_API_KEY_ID", &pinecone.UpdateAPIKeyParams{
          Name:  &name,
          Roles: &roles,
      })
      if err != nil {
          log.Fatalf("Failed to update API key: %v", err)
      }
      fmt.Printf("Successfully updated API key: %v\n", apiKey.Name)
  }
  ```

  ```hcl Terraform theme={null}
  # Requires Terraform provider v4.0.0 or later
  # Change the name or roles on an existing resource, then run `terraform apply`
  resource "pinecone_api_key" "example" {
    name       = "New API key name"
    project_id = "YOUR_PROJECT_ID"
    roles      = ["ProjectEditor"]
  }
  ```

  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
  PINECONE_API_KEY_ID="YOUR_API_KEY_ID"

  curl -X PATCH "https://api.pinecone.io/admin/api-keys/$PINECONE_API_KEY_ID" \
  	-H "X-Pinecone-Api-Version: 2026-04" \
  	-H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
  	-d '{
  		"name": "New API key name",
  		"roles": ["ProjectEditor"]
  	}'
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "key": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "New API key name",
      "project_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "roles": [
        "ProjectEditor"
      ]
    },
    "value": "string"
  }
  ```
</ResponseExample>


# Update a project
Source: https://docs.pinecone.io/reference/api/2026-04/admin/update_project

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml patch /admin/projects/{project_id}
Update a project's name, maximum number of Pods, or customer-managed encryption key (CMEK).


<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  const project = await admin.projects.update('YOUR_PROJECT_ID', {
    name: 'updated-example-project',
  });
  console.log(project);
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "fmt"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      name := "updated-example-project"
      project, err := adminClient.Project.Update(ctx, "YOUR_PROJECT_ID", &pinecone.UpdateProjectParams{
          Name: &name,
      })
      if err != nil {
          log.Fatalf("Failed to update project: %v", err)
      }
      fmt.Printf("Successfully updated project: %v\n", project.Name)
  }
  ```

  ```hcl Terraform theme={null}
  # Requires Terraform provider v4.0.0 or later
  # Change the name on an existing resource, then run `terraform apply`
  resource "pinecone_project" "example" {
    name = "updated-example-project"
  }
  ```

  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
  PROJECT_ID="YOUR_PROJECT_ID"

  curl -X PATCH "https://api.pinecone.io/admin/projects/$PROJECT_ID" \
    -H "accept: application/json" \
    -H "Content-Type: application/json" \
    -H "X-Pinecone-Api-Version: 2026-04" \
    -d '{
      "name": "updated-example-project"
      }'
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "updated-example-project",
    "max_pods": 0,
    "force_encryption_with_cmek": false,
    "organization_id": "string",
    "created_at": "2025-03-17T00:42:31.912Z"
  }
  ```
</ResponseExample>


# Update a service account
Source: https://docs.pinecone.io/reference/api/2026-04/admin/update_service_account

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml patch /admin/service-accounts/{service_account_id}
Update a service account's name; role bindings are managed through the role-binding endpoints.


<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  const serviceAccount = await admin.serviceAccounts.update('YOUR_SERVICE_ACCOUNT_ID', {
    name: 'ci-prod-renamed',
  });
  console.log(serviceAccount);
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "fmt"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      name := "ci-prod-renamed"
      sa, err := adminClient.ServiceAccount.Update(ctx, "YOUR_SERVICE_ACCOUNT_ID", &pinecone.UpdateServiceAccountParams{
          Name: &name,
      })
      if err != nil {
          log.Fatalf("Failed to update service account: %v", err)
      }
      fmt.Printf("Successfully updated service account: %v\n", sa.Name)
  }
  ```

  ```hcl Terraform theme={null}
  # Requires Terraform provider v4.0.0 or later
  # Change the name on an existing resource, then run `terraform apply`
  resource "pinecone_service_account" "ci_prod" {
    name = "ci-prod-renamed"
  }
  ```

  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
  PINECONE_SERVICE_ACCOUNT_ID="YOUR_SERVICE_ACCOUNT_ID"

  curl -X PATCH "https://api.pinecone.io/admin/service-accounts/$PINECONE_SERVICE_ACCOUNT_ID" \
  	-H "X-Pinecone-Api-Version: 2026-04" \
  	-H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
  	-d '{
  		"name": "ci-prod-renamed"
  	}'
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "id": "f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
    "name": "ci-prod-renamed",
    "client_id": "l3Ow0CmFyc4jOONcwiKUCRqQKN0tiCAn",
    "created_at": "2026-04-10T15:23:00Z",
    "updated_at": "2026-04-12T09:11:00Z"
  }
  ```
</ResponseExample>


# Configure an index
Source: https://docs.pinecone.io/reference/api/2026-04/control-plane/configure_index

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_control_2026-04.oas.yaml patch /indexes/{index_name}
Configure an existing index. For guidance and examples, see [Manage indexes](https://docs.pinecone.io/guides/manage-data/manage-indexes).

<RequestExample>
  ```shell curl theme={null}
  # EXAMPLE REQUEST 1: Serverless index (on-demand)
  # Enable deletion protection and add tags to an 
  # existing on-demand index.
  PINECONE_API_KEY="YOUR_API_KEY"
  INDEX_NAME="YOUR_INDEX_NAME"

  curl -X PATCH "https://api.pinecone.io/indexes/$INDEX_NAME" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2026-04" \
    -d '{
          "deletion_protection": "enabled",
          "tags": {
            "tag1": "value1",
            "tag2": "value2"
          }
        }'

  # EXAMPLE REQUEST 2: Serverless index (dedicated)
  # Add a replica to an existing dedicated index.
  PINECONE_API_KEY="YOUR_API_KEY"
  INDEX_NAME="YOUR_INDEX_NAME"

  curl -X PATCH "https://api.pinecone.io/indexes/$INDEX_NAME" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2026-04" \
    -d '{
          "spec": {
            "serverless": {
              "read_capacity": {
                "mode": "Dedicated",
                "dedicated": {
                  "node_type": "b1",
                  "scaling": "Manual",
                  "manual": {
                    "shards": 2,
                    "replicas": 2
                  }
                }
              }
            }
          }
        }'
  ```
</RequestExample>

<ResponseExample>
  ```jsonc curl theme={null}
  // EXAMPLE RESPONSE 1: Serverless index (on-demand)
  // Enable deletion protection and add tags to an 
  // existing on-demand index.
  {
    "name": "example-serverless-ondemand-index",
    "vector_type": "dense",
    "metric": "cosine",
    "dimension": 1024,
    "status": {
      "ready": true,
      "state": "Ready"
    },
    "host": "example-serverless-ondemand-index-bhnyigt.svc.aped-4627-b74a.pinecone.io",
    "spec": {
      "serverless": {
        "region": "us-east-1",
        "cloud": "aws",
        "read_capacity": {
          "mode": "OnDemand",
          "status": {
            "state": "Ready",
            "current_shards": null,
            "current_replicas": null
          }
        }
      }
    },
    "deletion_protection": "enabled",
    "tags": {
      "tag1": "value1",
      "tag2": "value2"
    },
    "embed": {
      "model": "llama-text-embed-v2",
      "field_map": {
        "text": "text"
      },
      "dimension": 1024,
      "metric": "cosine",
      "write_parameters": {
        "dimension": 1024,
        "input_type": "passage",
        "truncate": "END"
      },
      "read_parameters": {
        "dimension": 1024,
        "input_type": "query",
        "truncate": "END"
      },
      "vector_type": "dense"
    }
  }

  // EXAMPLE RESPONSE 2: Serverless index (dedicated)
  // Add a replica to an existing dedicated index.
  {
    "name": "example-serverless-dedicated-index",
    "vector_type": "dense",
    "metric": "cosine",
    "dimension": 1536,
    "status": {
      "ready": true,
      "state": "Ready"
    },
    "host": "example-serverless-dedicated-index-bhnyigt.svc.aped-4627-b74a.pinecone.io",
    "spec": {
      "serverless": {
        "region": "us-east-1",
        "cloud": "aws",
        "read_capacity": {
          "mode": "Dedicated",
          "dedicated": {
            "node_type": "b1",
            "scaling": "Manual",
            "manual": {
              "shards": 1,
              "replicas": 2 <-- desired state
            }
          },
          "status": {
            "state": "Scaling",
            "current_shards": 1,
            "current_replicas": 1 <-- current state
          }
        }
      }
    },
    "deletion_protection": "enabled",
    "tags": {
      "tag0": "value0"
    }
  }
  ```
</ResponseExample>


# Create an index with integrated embedding
Source: https://docs.pinecone.io/reference/api/2026-04/control-plane/create_for_model

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_control_2026-04.oas.yaml post /indexes/create-for-model
Create an index with integrated embedding.
With this type of index, you provide source text, and  Pinecone uses a [hosted embedding model](https://docs.pinecone.io/guides/index-data/create-an-index#embedding-models)  to convert the text automatically during [upsert](https://docs.pinecone.io/reference/api/2026-04/data-plane/upsert_records)  and [search](https://docs.pinecone.io/reference/api/2026-04/data-plane/search_records).  
For guidance and examples, see [Create an index](https://docs.pinecone.io/guides/index-data/create-an-index#integrated-embedding).

<RequestExample>
  ```shell curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"

  curl https://api.pinecone.io/indexes/create-for-model \
    -H "Content-Type: application/json" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2026-04" \
    -d '{
          "name": "integrated-dense-curl",
          "cloud": "aws",
          "region": "us-east-1",
          "embed": {
            "model": "llama-text-embed-v2",
            "metric": "cosine",
            "field_map": {
              "text": "chunk_text"
            },
            "write_parameters": {
              "input_type": "passage",
              "truncate": "END"
            },
            "read_parameters": {
              "input_type": "query",
              "truncate": "END"
            }
          }
        }'
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "id": "9dabb7cb-ec0a-4e2e-b79e-c7c997e592ce",
    "name": "integrated-dense-curl",
    "metric": "cosine",
    "dimension": 1024,
    "status": {
      "ready": false,
      "state": "Initializing"
    },
    "host": "integrated-dense-curl-govk0nt.svc.aped-4627-b74a.pinecone.io",
    "spec": {
      "serverless": {
        "region": "us-east-1",
        "cloud": "aws"
      }
    },
    "deletion_protection": "disabled",
    "tags": null,
    "embed": {
      "model": "llama-text-embed-v2",
      "field_map": {
        "text": "chunk_text"
      },
      "dimension": 1024,
      "metric": "cosine",
      "write_parameters": {
        "input_type": "passage",
        "truncate": "END"
      },
      "read_parameters": {
        "input_type": "query",
        "truncate": "END"
      }
    }
  }
  ```
</ResponseExample>


# Create an index
Source: https://docs.pinecone.io/reference/api/2026-04/control-plane/create_index

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_control_2026-04.oas.yaml post /indexes
Create a Pinecone index. This is where you specify the measure of similarity, the dimension of vectors to be stored in the index, which cloud provider you would like to deploy with, and more.
To restore from a backup, set `spec.serverless.source_backup_id` and specify the target `cloud` and `region`. Same-cloud cross-region restore is supported when available for the backup's source region. Cross-cloud restore is not supported.
For guidance and examples, see [Create an index](https://docs.pinecone.io/guides/index-data/create-an-index).


## Cloud regions

For serverless indexes, the `cloud` and `region` fields in `spec.serverless` accept the following values:

| Cloud   | Region                       | [Supported plans](https://www.pinecone.io/pricing/) | [Availability phase](/release-notes/feature-availability) |
| ------- | ---------------------------- | --------------------------------------------------- | --------------------------------------------------------- |
| `aws`   | `us-east-1` (Virginia)       | Starter, Builder, Standard, Enterprise              | General availability                                      |
| `aws`   | `us-west-2` (Oregon)         | Builder, Standard, Enterprise                       | General availability                                      |
| `aws`   | `eu-west-1` (Ireland)        | Builder, Standard, Enterprise                       | General availability                                      |
| `aws`   | `eu-central-1` (Frankfurt)   | Builder, Standard, Enterprise                       | General availability                                      |
| `aws`   | `ap-southeast-1` (Singapore) | Builder, Standard, Enterprise                       | General availability                                      |
| `gcp`   | `us-central1` (Iowa)         | Builder, Standard, Enterprise                       | General availability                                      |
| `gcp`   | `europe-west4` (Netherlands) | Builder, Standard, Enterprise                       | General availability                                      |
| `azure` | `eastus2` (Virginia)         | Builder, Standard, Enterprise                       | General availability                                      |

The cloud and region cannot be changed after a serverless index is created.

<Note>
  On the Starter plan, you can create serverless indexes in the `us-east-1` region of AWS only. To create indexes in other regions, [upgrade to the Builder, Standard, or Enterprise plan](/guides/organizations/manage-billing/upgrade-billing-plan).
</Note>

For BYOC indexes, set `spec.byoc.environment` to the environment ID provisioned for your account instead. See [Bring your own cloud](/guides/production/bring-your-own-cloud) for details.

<RequestExample>
  ```shell curl theme={null}
  # EXAMPLE REQUEST 1: Serverless index (on-demand)
  PINECONE_API_KEY="YOUR_API_KEY"
  curl -s "https://api.pinecone.io/indexes" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2026-04" \
    -d '{
          "name": "example-serverless-index",
          "vector_type": "dense",
          "dimension": 1536,
          "metric": "cosine",
          "spec": {
              "serverless": {
                  "cloud": "aws",
                  "region": "us-east-1"
              }
          },
          "tags": {
              "tag0": "value0"
          },
          "deletion_protection": "disabled"
        }'

  # EXAMPLE REQUEST 2: Serverless index (dedicated)
  PINECONE_API_KEY="YOUR_API_KEY"
  curl "https://api.pinecone.io/indexes" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2026-04" \
    -d '{
  		"name": "example-serverless-dedicated-index",
  		"dimension": 1536,
  		"metric": "cosine",
  		"deletion_protection": "enabled",
  		"tags": {
  			"tag0": "value0"
  		},
  		"vector_type": "dense",
  		"spec": {
  			"serverless": {
  				"cloud": "aws",
  				"region": "us-east-1",
  				"read_capacity": {
  					"mode": "Dedicated",
  					"dedicated": {
  						"node_type": "b1",
  						"scaling": "Manual",
  						"manual": {
  							"shards": 2,
  							"replicas": 1
  						}
  					}
  				}
  			}
  		}
  	}'

  # EXAMPLE REQUEST 3: BYOC index
  PINECONE_API_KEY="YOUR_API_KEY"
  curl -s "https://api.pinecone.io/indexes" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2026-04" \
    -d '{
          "name": "example-byoc-index",
          "vector_type": "dense",
          "dimension": 1536,
          "metric": "cosine",
          "spec": {
              "byoc": {
                  "environment": "aws-us-east-1-b921"
              }
          },
          "tags": {
              "tag0": "value0"
          },
          "deletion_protection": "disabled"
        }'
  ```
</RequestExample>

<ResponseExample>
  ```jsonc curl theme={null}
  // EXAMPLE RESPONSE 1: Serverless index (on-demand)
  {
    "name": "example-serverless-ondemand-index",
    "vector_type": "dense",
    "metric": "cosine",
    "dimension": 1536,
    "status": {
      "ready": false,
      "state": "Initializing"
    },
    "host": "example-serverless-ondemand-index-bhnyigt.svc.aped-4627-b74a.pinecone.io",
    "spec": {
      "serverless": {
        "region": "us-east-1",
        "cloud": "aws",
        "read_capacity": {
          "mode": "OnDemand",
          "status": {
            "state": "Ready",
            "current_shards": null,
            "current_replicas": null
          }
        }
      }
    },
    "deletion_protection": "disabled",
    "tags": {
      "tag0": "value0"
    }
  }

  // EXAMPLE RESPONSE 2: Serverless index (dedicated)
  {
  	"name": "example-serverless-dedicated-index",
  	"vector_type": "dense",
  	"metric": "cosine",
  	"dimension": 1536,
  	"status": {
  		"ready": false,
  		"state": "Initializing"
  	},
  	"host": "example-serverless-dedicated-index-bhnyigt.svc.aped-4627-b74a.pinecone.io",
  	"spec": {
  		"serverless": {
  			"region": "us-east-1",
  			"cloud": "aws",
  			"read_capacity": {
  				"mode": "Dedicated",
  				"dedicated": {
  					"node_type": "b1",
  					"scaling": "Manual",
  					"manual": {
  						"shards": 2,
  						"replicas": 1
  					}
  				},
  				"status": {
  					"state": "Migrating",
  					"current_shards": null,
  					"current_replicas": null
  				}
  			}
  		}
  	},
  	"deletion_protection": "enabled",
  	"tags": {
  		"tag0": "value0"
  	}
  }

  // EXAMPLE RESPONSE 3: BYOC index
  {
      "name": "example-byoc-index",
      "vector_type": "dense",
      "metric": "cosine",
      "dimension": 1536,
      "status": {
          "ready": true,
          "state": "Ready"
      },
      "host": "example-byoc-index-govk0nt.svc.private.aped-4627-b74a.pinecone.io",
      "spec": {
          "byoc": {
              "environment": "aws-us-east-1-b921"
          }
      },
      "deletion_protection": "disabled",
      "tags": {
          "tag0": "value0"
      }
  }
  ```
</ResponseExample>


# Delete an index
Source: https://docs.pinecone.io/reference/api/2026-04/control-plane/delete_index

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_control_2026-04.oas.yaml delete /indexes/{index_name}
Delete an existing index.

<RequestExample>
  ```shell curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"

  curl -i -X DELETE "https://api.pinecone.io/indexes/docs-example" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2026-04"
  ```
</RequestExample>

<ResponseExample />


# Describe an index
Source: https://docs.pinecone.io/reference/api/2026-04/control-plane/describe_index

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_control_2026-04.oas.yaml get /indexes/{index_name}
Get a description of an index.

<RequestExample>
  ```shell curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  INDEX_NAME="YOUR_INDEX_NAME"

  curl "https://api.pinecone.io/indexes/$INDEX_NAME" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2026-04" 
  ```
</RequestExample>

<ResponseExample>
  ```jsonc curl theme={null}
  // EXAMPLE RESPONSE 1: Serverless index (on-demand)
  {
    "name": "example-serverless-ondemand-index",
    "vector_type": "dense",
    "metric": "cosine",
    "dimension": 1024,
    "status": {
      "ready": true,
      "state": "Ready"
    },
    "host": "example-serverless-ondemand-index-bhnyigt.svc.aped-4627-b74a.pinecone.io",
    "spec": {
      "serverless": {
        "region": "us-east-1",
        "cloud": "aws",
        "read_capacity": {
          "mode": "OnDemand",
          "status": {
            "state": "Ready",
            "current_shards": null,
            "current_replicas": null
          }
        }
      }
    },
    "deletion_protection": "enabled",
    "tags": {
      "tag1": "value1",
      "tag2": "value2"
    },
    "embed": {
      "model": "llama-text-embed-v2",
      "field_map": {
        "text": "text"
      },
      "dimension": 1024,
      "metric": "cosine",
      "write_parameters": {
        "dimension": 1024,
        "input_type": "passage",
        "truncate": "END"
      },
      "read_parameters": {
        "dimension": 1024,
        "input_type": "query",
        "truncate": "END"
      },
      "vector_type": "dense"
    }
  }

  // EXAMPLE RESPONSE 2: Serverless index (dedicated)
  {
    "name": "example-serverless-dedicated-index",
    "vector_type": "dense",
    "metric": "cosine",
    "dimension": 1536,
    "status": {
      "ready": true,
      "state": "Ready"
    },
    "host": "example-serverless-dedicated-index-bhnyigt.svc.aped-4627-b74a.pinecone.io",
    "spec": {
      "serverless": {
        "region": "us-east-1",
        "cloud": "aws",
        "read_capacity": {
          "mode": "Dedicated",
          "dedicated": {
            "node_type": "b1",
            "scaling": "Manual",
            "manual": {
              "shards": 1,
              "replicas": 2
            }
          },
          "status": {
            "state": "Scaling",
            "current_shards": 1,
            "current_replicas": 1
          }
        }
      }
    },
    "deletion_protection": "enabled",
    "tags": {
      "tag0": "value0",
      "tag1": "value1"
    }
  }
  ```
</ResponseExample>


# List indexes
Source: https://docs.pinecone.io/reference/api/2026-04/control-plane/list_indexes

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_control_2026-04.oas.yaml get /indexes
List all indexes in a project.

<RequestExample>
  ```shell curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"

  curl -i -X GET "https://api.pinecone.io/indexes" \
  -H "Api-Key: $PINECONE_API_KEY" \
  -H "X-Pinecone-Api-Version: 2026-04"
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "indexes": [
      {
        "name": "example-serverless-dedicated-index",
        "vector_type": "dense",
        "metric": "cosine",
        "dimension": 1536,
        "status": {
          "ready": true,
          "state": "Ready"
        },
        "host": "example-serverless-dedicated-index-bhnyigt.svc.aped-4627-b74a.pinecone.io",
        "spec": {
          "serverless": {
            "region": "us-east-1",
            "cloud": "aws",
            "read_capacity": {
              "mode": "Dedicated",
              "dedicated": {
                "node_type": "b1",
                "scaling": "Manual",
                "manual": {
                  "shards": 1,
                  "replicas": 2
                }
              },
              "status": {
                "state": "Scaling",
                "current_shards": 1,
                "current_replicas": 1
              }
            }
          }
        },
        "deletion_protection": "enabled",
        "tags": {
          "tag0": "value0",
          "tag1": "value1"
        }
      },
      {
        "name": "example-serverless-ondemand-index",
        "vector_type": "dense",
        "metric": "cosine",
        "dimension": 1024,
        "status": {
          "ready": true,
          "state": "Ready"
        },
        "host": "example-serverless-ondemand-index-bhnyigt.svc.aped-4627-b74a.pinecone.io",
        "spec": {
          "serverless": {
            "region": "us-east-1",
            "cloud": "aws",
            "read_capacity": {
              "mode": "OnDemand",
              "status": {
                "state": "Ready",
                "current_shards": null,
                "current_replicas": null
              }
            }
          }
        },
        "deletion_protection": "enabled",
        "tags": {
          "tag1": "value1",
          "tag2": "value2"
        },
        "embed": {
          "model": "llama-text-embed-v2",
          "field_map": {
            "text": "text"
          },
          "dimension": 1024,
          "metric": "cosine",
          "write_parameters": {
            "dimension": 1024,
            "input_type": "passage",
            "truncate": "END"
          },
          "read_parameters": {
            "dimension": 1024,
            "input_type": "query",
            "truncate": "END"
          },
          "vector_type": "dense"
        }
      },
      {
        "name": "example-pod-index",
        "vector_type": "dense",
        "metric": "cosine",
        "dimension": 768,
        "status": {
          "ready": true,
          "state": "Ready"
        },
        "host": "example-pod-index-bhnyigt.svc.us-east-1-aws.pinecone.io",
        "spec": {
          "pod": {
            "replicas": 1,
            "shards": 1,
            "pods": 1,
            "pod_type": "s1.x1",
            "environment": "us-east-1-aws"
          }
        },
        "deletion_protection": "disabled",
        "tags": null
      }
    ]
  }
  ```
</ResponseExample>


# Create a namespace
Source: https://docs.pinecone.io/reference/api/2026-04/data-plane/createnamespace

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_data_2026-04.oas.yaml post /namespaces
Create a namespace in a serverless index.

For guidance and examples, see [Manage namespaces](https://docs.pinecone.io/guides/manage-data/manage-namespaces).

**Note:** This operation is not supported for pod-based indexes.

<RequestExample>
  ```bash curl theme={null}
  # To get the unique host for an index,
  # see https://docs.pinecone.io/guides/manage-data/target-an-index
  PINECONE_API_KEY="YOUR_API_KEY"
  INDEX_HOST="INDEX_HOST"

  curl "https://$INDEX_HOST/namespaces" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2026-04" \
    -d '{
          "name": "example-namespace",
          "schema": {
  		  "fields": { 
              "document_id": {"filterable": true},
              "document_title": {"filterable": true},
              "chunk_number": {"filterable": true},
              "document_url": {"filterable": true},
              "created_at": {"filterable": true}
            }
          }
        }'
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
      "name": "example-namespace",
      "record_count": "0",
      "schema": {
          "fields": {
              "document_title": {
                  "filterable": true
              },
              "document_url": {
                  "filterable": true
              },
              "chunk_number": {
                  "filterable": true
              },
              "document_id": {
                  "filterable": true
              },
              "created_at": {
                  "filterable": true
              }
          }
      }
  }
  ```
</ResponseExample>


# Delete a namespace
Source: https://docs.pinecone.io/reference/api/2026-04/data-plane/deletenamespace

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_data_2026-04.oas.yaml delete /namespaces/{namespace}
Delete a namespace from a serverless index. Deleting a namespace is irreversible; all data in the namespace is permanently deleted.

For guidance and examples, see [Manage namespaces](https://docs.pinecone.io/guides/manage-data/manage-namespaces).

**Note:** This operation is not supported for pod-based indexes.

<RequestExample>
  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  INDEX_HOST="YOUR_INDEX_HOST"
  NAMESPACE="YOUR_NAMESPACE" # To target the default namespace, use "__default__".

  curl -X DELETE "https://$INDEX_HOST/namespaces/$NAMESPACE" \
      -H "Api-Key: $PINECONE_API_KEY" \
      -H "X-Pinecone-Api-Version: 2026-04"
  ```
</RequestExample>

<ResponseExample />


# Get index stats
Source: https://docs.pinecone.io/reference/api/2026-04/data-plane/describeindexstats

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_data_2026-04.oas.yaml post /describe_index_stats
Return statistics about the contents of an index, including the vector count per namespace, the number of dimensions, and the index fullness.

Serverless indexes scale automatically as needed, so index fullness is relevant only for pod-based indexes.

<Note>
  Index fullness is also relevant for [dedicated read nodes](/guides/index-data/dedicated-read-nodes#index-fullness). The response includes `memoryFullness` and `storageFullness` alongside `indexFullness`, which summarizes overall capacity usage. For serverless on-demand indexes, all three values are typically `0` because storage and compute scale automatically. For dedicated indexes, monitor these values and [add shards](/guides/index-data/dedicated-read-nodes#add-or-remove-shards) before the index reaches capacity.
</Note>

<RequestExample>
  ```shell curl theme={null}
  # To get the unique host for an index,
  # see https://docs.pinecone.io/guides/manage-data/target-an-index
  PINECONE_API_KEY="YOUR_API_KEY"
  INDEX_HOST="YOUR_INDEX_HOST"

  curl -X POST "https://$INDEX_HOST/describe_index_stats" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2026-04"
  ```
</RequestExample>

<ResponseExample>
  ```jsonc curl theme={null}
  // EXAMPLE RESPONSE 1: Serverless index (on-demand)
  {
    "namespaces": {
      "example-namespace": {
        "vectorCount": 10000
      }
    },
    "indexFullness": 0,
    "totalVectorCount": 10000,
    "dimension": 1024,
    "metric": "cosine",
    "vectorType": "dense",
    "memoryFullness": 0,
    "storageFullness": 0
  }

  // EXAMPLE RESPONSE 2: Serverless index (dedicated read nodes)
  {
    "namespaces": {
      "example-namespace": {
        "vectorCount": 705000
      }
    },
    "indexFullness": 0.01,
    "totalVectorCount": 705000,
    "dimension": 1536,
    "metric": "cosine",
    "vectorType": "dense",
    "memoryFullness": 0.01,
    "storageFullness": 0.01
  }
  ```
</ResponseExample>


# Describe a namespace
Source: https://docs.pinecone.io/reference/api/2026-04/data-plane/describenamespace

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_data_2026-04.oas.yaml get /namespaces/{namespace}
Describe a namespace in a serverless index, including the total number of vectors in the namespace.

For guidance and examples, see [Manage namespaces](https://docs.pinecone.io/guides/manage-data/manage-namespaces).

**Note:** This operation is not supported for pod-based indexes.

<RequestExample>
  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  INDEX_HOST="YOUR_INDEX_HOST"
  NAMESPACE="YOUR_NAMESPACE"  # To target the default namespace, use "__default__".

  curl "https://$INDEX_HOST/namespaces/$NAMESPACE" \
      -H "Api-Key: $PINECONE_API_KEY" \
      -H "X-Pinecone-Api-Version: 2026-04"
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "name": "example-namespace",
    "record_count": 20000
  }
  ```
</ResponseExample>


# Fetch records
Source: https://docs.pinecone.io/reference/api/2026-04/data-plane/fetch

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_data_2026-04.oas.yaml get /vectors/fetch
Look up and return records by ID from a single namespace. The returned records include the vector data and/or metadata.
For on-demand indexes, since vector values are retrieved from object storage, fetch operations may have increased latency. If you only need metadata or IDs, consider using the query operation with `includeValues` set to `false` instead.
For guidance and examples, see [Fetch data](https://docs.pinecone.io/guides/manage-data/fetch-data).

<RequestExample>
  ```shell curl theme={null}
  # To get the unique host for an index,
  # see https://docs.pinecone.io/guides/manage-data/target-an-index
  PINECONE_API_KEY="YOUR_API_KEY"
  INDEX_HOST="INDEX_HOST"

  curl -X GET "https://$INDEX_HOST/vectors/fetch?ids=id-1&ids=id-2&namespace=example-namespace" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2026-04"
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "vectors": {
      "id-1": {
        "id": "id-1",
        "values": [0.568879, 0.632687092, 0.856837332, ...]
      },
      "id-2": {
        "id": "id-2",
        "values": [0.00891787093, 0.581895, 0.315718859, ...]
      }
    },
    "namespace": "example-namespace",
    "usage": {"readUnits": 1},
  }
  ```
</ResponseExample>


# Fetch records by metadata
Source: https://docs.pinecone.io/reference/api/2026-04/data-plane/fetch_by_metadata

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_data_2026-04.oas.yaml post /vectors/fetch_by_metadata
Look up and return records by metadata from a single namespace. The returned records include the vector data and metadata.
For guidance and examples, see [Fetch data](https://docs.pinecone.io/guides/manage-data/fetch-data).

<RequestExample>
  ```shell curl theme={null}
  # To get the unique host for an index,
  # see https://docs.pinecone.io/guides/manage-data/target-an-index
  PINECONE_API_KEY="YOUR_API_KEY"
  INDEX_HOST="INDEX_HOST"

  curl -X POST "https://$INDEX_HOST/vectors/fetch_by_metadata" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "Content-Type: application/json" \
    -H "X-Pinecone-Api-Version: 2026-04" \
    -d '{
      "namespace": "__default__",
      "filter": {"genre": {"$eq": "Action/Adventure"}},
      "limit": 2
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "vectors": {
      "0": {
        "id": "0",
        "values": [
          0.0234527588, 0.0291595459 ...
        ],
        "metadata": {
          "box-office": 2923706026,
          "genre": "Action/Adventure",
          "summary": "On the alien world of Pandora, paraplegic Marine Jake Sully uses an avatar to walk again and becomes torn between his mission and protecting the planet's indigenous Na'vi people. The film stars Sam Worthington, Zoe Saldana, and Sigourney Weaver.",
          "title": "Avatar",
          "year": 2009
        }
      },
      "1": {
        "id": "1",
        "values": [
          0.0397644043, 0.013053894, ...
        ],
        "metadata": {
          "box-office": 2799439100,
          "genre": "Action/Adventure",
          "summary": "In the aftermath of Thanos wiping out half of the universe, the remaining Avengers assemble once more to undo the chaos, leading to a time-traveling adventure. Stars Robert Downey Jr., Chris Evans, and Scarlett Johansson.",
          "title": "Avengers: Endgame",
          "year": 2019
        }
      }
    },
    "namespace": "__default__",
    "usage": {
      "readUnits": 1
    },
    "pagination": {
      "next": "Tm90aGluZyB0byBzZWUgaGVyZQo="
    }
  }
  ```
</ResponseExample>


# List namespaces
Source: https://docs.pinecone.io/reference/api/2026-04/data-plane/listnamespaces

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_data_2026-04.oas.yaml get /namespaces
List all namespaces in a serverless index.

Up to 100 namespaces are returned at a time by default, in sorted order (bitwise “C” collation). If the `limit` parameter is set, up to that number of namespaces are returned instead. Whenever there are additional namespaces to return, the response also includes a `pagination_token` that you can use to get the next batch of namespaces. When the response does not include a `pagination_token`, there are no more namespaces to return.

For guidance and examples, see [Manage namespaces](https://docs.pinecone.io/guides/manage-data/manage-namespaces).

**Note:** This operation is not supported for pod-based indexes.

<RequestExample>
  ```bash curl theme={null}
  # To get the unique host for an index,
  # see https://docs.pinecone.io/guides/manage-data/target-an-index
  PINECONE_API_KEY="YOUR_API_KEY"
  INDEX_HOST="INDEX_HOST"

  curl "https://$INDEX_HOST/namespaces" \
      -H "Api-Key: $PINECONE_API_KEY" \
      -H "X-Pinecone-Api-Version: 2026-04"
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "namespaces": [
      {
        "name": "example-namespace",
        "record_count": 20000
      },
      {
        "name": "example-namespace2",
        "record_count": 10500
      },
      ...
    ],
    "pagination": {
      "next": "Tm90aGluZyB0byBzZWUgaGVyZQo="
    }
  }
  ```
</ResponseExample>


# Upsert records
Source: https://docs.pinecone.io/reference/api/2026-04/data-plane/upsert

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_data_2026-04.oas.yaml post /vectors/upsert
Upsert records into a namespace. If a new value is upserted for an existing record ID, it will overwrite the previous value.

For guidance, examples, and limits, see [Upsert data](https://docs.pinecone.io/guides/index-data/upsert-data).

<Tip>
  To control costs when ingesting large datasets (10,000,000+ records), use [import](/guides/index-data/import-data) instead of upsert.
</Tip>

<RequestExample>
  ```shell curl theme={null}
  # To get the unique host for an index,
  # see https://docs.pinecone.io/guides/manage-data/target-an-index
  PINECONE_API_KEY="YOUR_API_KEY"
  INDEX_HOST="INDEX_HOST"

  curl "https://$INDEX_HOST/vectors/upsert" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H 'Content-Type: application/json' \
    -H "X-Pinecone-Api-Version: 2026-04" \
    -d '{
      "vectors": [
        {
          "id": "vec1",
          "values": [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1],
          "metadata": {"genre": "comedy", "year": 2020}
        },
        {
          "id": "vec2",
          "values": [0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2],
          "metadata": {"genre": "documentary", "year": 2019}
        }
      ],
      "namespace": "example-namespace"
    }'
  ```
</RequestExample>

<ResponseExample />

```
```


# Upsert text
Source: https://docs.pinecone.io/reference/api/2026-04/data-plane/upsert_records

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_data_2026-04.oas.yaml post /records/namespaces/{namespace}/upsert
Upsert text into a namespace. Pinecone converts the text to vectors automatically using the hosted embedding model associated with the index.

Upserting text is supported only for [indexes with integrated embedding](https://docs.pinecone.io/guides/index-data/create-an-index#embedding-models).

For guidance, examples, and limits, see [Upsert data](https://docs.pinecone.io/guides/index-data/upsert-data).

<RequestExample>
  ```shell curl theme={null}
  # To get the unique host for an index,
  # see https://docs.pinecone.io/guides/manage-data/target-an-index
  INDEX_HOST="INDEX_HOST"
  NAMESPACE="YOUR_NAMESPACE"
  PINECONE_API_KEY="YOUR_API_KEY"

  # Upsert records into a namespace
  # `chunk_text` fields are converted to dense vectors
  # `category` fields are stored as metadata
  curl "https://$INDEX_HOST/records/namespaces/$NAMESPACE/upsert" \
    -H "Content-Type: application/x-ndjson" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2026-04" \
    -d '{"_id": "rec1", "chunk_text": "Apples are a great source of dietary fiber, which supports digestion and helps maintain a healthy gut.", "category": "digestive system"}
        {"_id": "rec2", "chunk_text": "Apples originated in Central Asia and have been cultivated for thousands of years, with over 7,500 varieties available today.", "category": "cultivation"}
        {"_id": "rec3", "chunk_text": "Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases.", "category": "immune system"}
        {"_id": "rec4", "chunk_text": "The high fiber content in apples can also help regulate blood sugar levels, making them a favorable snack for people with diabetes.", "category": "endocrine system"}'
  ```
</RequestExample>

<ResponseExample />


# Describe a model
Source: https://docs.pinecone.io/reference/api/2026-04/inference/describe_model

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/inference_2026-04.oas.yaml get /models/{model_name}
Get a description of a model hosted by Pinecone. 

You can use hosted models as an integrated part of Pinecone operations or for standalone embedding and reranking. For more details, see [Vector embedding](https://docs.pinecone.io/guides/index-data/indexing-overview#vector-embedding) and [Rerank results](https://docs.pinecone.io/guides/search/rerank-results).

<RequestExample>
  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"

  curl "https://api.pinecone.io/models/llama-text-embed-v2" \
      -H "Api-Key: $PINECONE_API_KEY" \
      -H "X-Pinecone-Api-Version: 2026-04"
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "model": "llama-text-embed-v2",
    "short_description": "A high performance dense embedding model optimized for multilingual and cross-lingual text question-answering retrieval with support for long documents (up to 2048 tokens) and dynamic embedding size (Matryoshka Embeddings).",
    "type": "embed",
    "vector_type": "dense",
    "default_dimension": 1024,
    "modality": "text",
    "max_sequence_length": 2048,
    "max_batch_size": 96,
    "provider_name": "NVIDIA",
    "supported_metrics": [
      "Cosine",
      "DotProduct"
    ],
    "supported_dimensions": [
      384,
      512,
      768,
      1024,
      2048
    ],
    "supported_parameters": [
      {
        "parameter": "input_type",
        "required": true,
        "type": "one_of",
        "value_type": "string",
        "allowed_values": [
          "query",
          "passage"
        ]
      },
      {
        "parameter": "truncate",
        "required": false,
        "default": "END",
        "type": "one_of",
        "value_type": "string",
        "allowed_values": [
          "END",
          "NONE",
          "START"
        ]
      },
      {
        "parameter": "dimension",
        "required": false,
        "default": 1024,
        "type": "one_of",
        "value_type": "integer",
        "allowed_values": [
          384,
          512,
          768,
          1024,
          2048
        ]
      }
    ]
  }
  ```
</ResponseExample>


# Generate vectors
Source: https://docs.pinecone.io/reference/api/2026-04/inference/generate-embeddings

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/inference_2026-04.oas.yaml post /embed
Generate vector embeddings for input data. This endpoint uses Pinecone's [hosted embedding models](https://docs.pinecone.io/guides/index-data/create-an-index#embedding-models).

<RequestExample>
  ```shell curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"

  curl https://api.pinecone.io/embed \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "Content-Type: application/json" \
    -H "X-Pinecone-Api-Version: 2026-04" \
    -d '{
        "model": "llama-text-embed-v2",
        "parameters": {
          "input_type": "passage",
          "truncate": "END"
        },
        "inputs": [
          {"text": "Apple is a popular fruit known for its sweetness and crisp texture."},
          {"text": "The tech company Apple is known for its innovative products like the iPhone."},
          {"text": "Many people enjoy eating apples as a healthy snack."},
          {"text": "Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces."},
          {"text": "An apple a day keeps the doctor away, as the saying goes."},
          {"text": "Apple Computer Company was founded on April 1, 1976, by Steve Jobs, Steve Wozniak, and Ronald Wayne as a partnership."}
        ]
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "data": [
      {
        "values": [
          0.04925537109375,
          -0.01313018798828125,
          -0.0112762451171875,
          ...
        ]
      }, 
      ...
    ],
    "model": "llama-text-embed-v2",
    "usage": {
      "total_tokens": 130
    }
  }
  ```
</ResponseExample>


# List available models
Source: https://docs.pinecone.io/reference/api/2026-04/inference/list_models

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/inference_2026-04.oas.yaml get /models
List the embedding and reranking models hosted by Pinecone. 

You can use hosted models as an integrated part of Pinecone operations or for standalone embedding and reranking. For more details, see [Vector embedding](https://docs.pinecone.io/guides/index-data/indexing-overview#vector-embedding) and [Rerank results](https://docs.pinecone.io/guides/search/rerank-results).

<RequestExample>
  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"

  curl "https://api.pinecone.io/models" \
      -H "Api-Key: $PINECONE_API_KEY" \
      -H "X-Pinecone-Api-Version: 2026-04"
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "models": [
      {
        "model": "llama-text-embed-v2",
        "short_description": "A high performance dense embedding model optimized for multilingual and cross-lingual text question-answering retrieval with support for long documents (up to 2048 tokens) and dynamic embedding size (Matryoshka Embeddings).",
        "type": "embed",
        "vector_type": "dense",
        "default_dimension": 1024,
        "modality": "text",
        "max_sequence_length": 2048,
        "max_batch_size": 96,
        "provider_name": "NVIDIA",
        "supported_metrics": [
          "Cosine",
          "DotProduct"
        ],
        "supported_dimensions": [
          384,
          512,
          768,
          1024,
          2048
        ],
        "supported_parameters": [
          {
            "parameter": "input_type",
            "required": true,
            "type": "one_of",
            "value_type": "string",
            "allowed_values": [
              "query",
              "passage"
            ]
          },
          {
            "parameter": "truncate",
            "required": false,
            "default": "END",
            "type": "one_of",
            "value_type": "string",
            "allowed_values": [
              "END",
              "NONE",
              "START"
            ]
          },
          {
            "parameter": "dimension",
            "required": false,
            "default": 1024,
            "type": "one_of",
            "value_type": "integer",
            "allowed_values": [
              384,
              512,
              768,
              1024,
              2048
            ]
          }
        ]
      },
      {
        "model": "multilingual-e5-large",
        "short_description": "A high-performance dense embedding model trained on a mixture of multilingual datasets. It works well on messy data and short queries expected to return medium-length passages of text (1-2 paragraphs)",
        "type": "embed",
        "vector_type": "dense",
        "default_dimension": 1024,
        "modality": "text",
        "max_sequence_length": 507,
        "max_batch_size": 96,
        "provider_name": "Microsoft",
        "supported_metrics": [
          "Cosine",
          "Euclidean"
        ],
        "supported_dimensions": [
          1024
        ],
        "supported_parameters": [
          {
            "parameter": "input_type",
            "required": true,
            "type": "one_of",
            "value_type": "string",
            "allowed_values": [
              "query",
              "passage"
            ]
          },
          {
            "parameter": "truncate",
            "required": false,
            "default": "END",
            "type": "one_of",
            "value_type": "string",
            "allowed_values": [
              "END",
              "NONE"
            ]
          }
        ]
      },
      {
        "model": "pinecone-sparse-english-v0",
        "short_description": "A sparse embedding model for converting text to sparse vectors for keyword or hybrid semantic/keyword search. Built on the innovations of the DeepImpact architecture.",
        "type": "embed",
        "vector_type": "sparse",
        "modality": "text",
        "max_sequence_length": 512,
        "max_batch_size": 96,
        "provider_name": "Pinecone",
        "supported_metrics": [
          "DotProduct"
        ],
        "supported_parameters": [
          {
            "parameter": "input_type",
            "required": true,
            "type": "one_of",
            "value_type": "string",
            "allowed_values": [
              "query",
              "passage"
            ]
          },
          {
            "parameter": "truncate",
            "required": false,
            "default": "END",
            "type": "one_of",
            "value_type": "string",
            "allowed_values": [
              "END",
              "NONE"
            ]
          },
          {
            "parameter": "return_tokens",
            "required": false,
            "default": false,
            "type": "any",
            "value_type": "boolean"
          }
        ]
      },
      {
        "model": "bge-reranker-v2-m3",
        "short_description": "A high-performance, multilingual reranking model that works well on messy data and short queries expected to return medium-length passages of text (1-2 paragraphs)",
        "type": "rerank",
        "modality": "text",
        "max_sequence_length": 1024,
        "max_batch_size": 100,
        "provider_name": "BAAI",
        "supported_parameters": [
          {
            "parameter": "truncate",
            "required": false,
            "default": "NONE",
            "type": "one_of",
            "value_type": "string",
            "allowed_values": [
              "END",
              "NONE"
            ]
          }
        ]
      },
      {
        "model": "cohere-rerank-3.5",
        "short_description": "Cohere's leading reranking model, balancing performance and latency for a wide range of enterprise search applications.",
        "type": "rerank",
        "modality": "text",
        "max_sequence_length": 40000,
        "max_batch_size": 200,
        "provider_name": "Cohere",
        "supported_parameters": [
          {
            "parameter": "max_chunks_per_doc",
            "required": false,
            "default": 3072,
            "type": "numeric_range",
            "value_type": "integer",
            "min": 1,
            "max": 3072
          }
        ]
      },
      {
        "model": "pinecone-rerank-v0",
        "short_description": "A state of the art reranking model that out-performs competitors on widely accepted benchmarks. It can handle chunks up to 512 tokens (1-2 paragraphs)",
        "type": "rerank",
        "modality": "text",
        "max_sequence_length": 512,
        "max_batch_size": 100,
        "provider_name": "Pinecone",
        "supported_parameters": [
          {
            "parameter": "truncate",
            "required": false,
            "default": "END",
            "type": "one_of",
            "value_type": "string",
            "allowed_values": [
              "END",
              "NONE"
            ]
          }
        ]
      }
    ]
  }
  ```
</ResponseExample>


# Rerank results
Source: https://docs.pinecone.io/reference/api/2026-04/inference/rerank

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/inference_2026-04.oas.yaml post /rerank
Rerank results according to their relevance to a query.

For guidance and examples, see [Rerank results](https://docs.pinecone.io/guides/search/rerank-results).

<RequestExample>
  ```shell curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"

  curl https://api.pinecone.io/rerank \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "X-Pinecone-Api-Version: 2026-04" \
    -H "Api-Key: $PINECONE_API_KEY" \
  -d '{
    "model": "bge-reranker-v2-m3",
    "query": "The tech company Apple is known for its innovative products like the iPhone.",
    "return_documents": true,
    "top_n": 4,
    "documents": [
      {"id": "vec1", "text": "Apple is a popular fruit known for its sweetness and crisp texture."},
      {"id": "vec2", "text": "Many people enjoy eating apples as a healthy snack."},
      {"id": "vec3", "text": "Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces."},
      {"id": "vec4", "text": "An apple a day keeps the doctor away, as the saying goes."}
    ],
    "parameters": {
      "truncate": "END"
    }
  }'
  ```
</RequestExample>

<ResponseExample>
  ```JSON curl theme={null}
  {
    "data":[
      {
        "index":2,
        "document":{
          "id":"vec3",
          "text":"Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces."
        },
        "score":0.47654688
      },
      {
        "index":0,
        "document":{
          "id":"vec1",
          "text":"Apple is a popular fruit known for its sweetness and crisp texture."
        },
        "score":0.047963805
      },
      {
        "index":3,
        "document":{
          "id":"vec4",
          "text":"An apple a day keeps the doctor away, as the saying goes."
        },
        "score":0.007587992
      },
      {
        "index":1,
        "document":{
          "id":"vec2",
          "text":"Many people enjoy eating apples as a healthy snack."
        },
        "score":0.0006491712
      }
    ],
    "usage":{
      "rerank_units":1
    }
  }
  ```
</ResponseExample>


# Authentication
Source: https://docs.pinecone.io/reference/api/authentication

Pinecone API authentication guide covering API key generation, SDK client setup, and HTTP header configuration for authorized requests.

All requests to [Pinecone APIs](/reference/api/introduction) must contain a valid [API key](/guides/production/security-overview#api-keys) for the target project.

## Get an API key

[Create a new API key](https://app.pinecone.io/organizations/-/projects/-/keys) in the Pinecone console, or use the connect widget below to generate a key.

<div>
  <div>
    <div>
      <div />
    </div>
  </div>
</div>

Copy your generated key:

```
PINECONE_API_KEY="{{YOUR_API_KEY}}"

# This API key has ReadWrite access to all indexes in your project.
```

## Initialize a client

When using a [Pinecone SDK](/reference/pinecone-sdks), initialize a client object with your API key and then reuse the authenicated client in subsquent function calls. For example:

<CodeGroup>
  ```Python Python theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone
  from pinecone import ServerlessSpec

  pc = Pinecone(api_key='YOUR_API_KEY')

  # Creates an index using the API key stored in the client 'pc'.
  pc.create_index(
      name="docs-example",
      dimension=1536,
      metric="cosine",
      spec=ServerlessSpec(
          cloud='aws', 
          region='us-east-1'
      ) 
  ) 
  ```

  ```JavaScript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone';

  const pc = new Pinecone({
      apiKey: 'YOUR_API_KEY' 
  });

  // Creates an index using the API key stored in the client 'pc'.
  await pc.createIndex({
      name: 'docs-example',
      dimension: 1536,
      metric: 'cosine',
      spec: { 
          serverless: { 
              cloud: 'aws', 
              region: 'us-east-1' 
          }
      } 
  }) 
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Pinecone;
  import org.openapitools.db_control.client.model.IndexModel;
  import org.openapitools.db_control.client.model.DeletionProtection;

  public class CreateServerlessIndexExample {
      public static void main(String[] args) {
          Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build();

          // Creates an index using the API key stored in the client 'pc'.
          pc.createServerlessIndex("docs-example", "cosine", 1536, "aws", "us-east-1");
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "fmt"
      "log"

      "github.com/pinecone-io/go-pinecone/v3/pinecone"
  )

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

  	indexName := "docs-example"
  	vectorType := "dense"
      dimension := int32(1536)
      metric := pinecone.Cosine
  	deletionProtection := pinecone.DeletionProtectionDisabled

      idx, err := pc.CreateServerlessIndex(ctx, &pinecone.CreateServerlessIndexRequest{
          Name:               indexName,
          VectorType:         &vectorType,
          Dimension:          &dimension,
          Metric:             &metric,
          Cloud:              pinecone.Aws,
          Region:             "us-east-1",
          DeletionProtection: &deletionProtection,
      })
      if err != nil {
          log.Fatalf("Failed to create serverless index: %v", err)
      } else {
          fmt.Printf("Successfully created serverless index: %v", idx.Name)
      }
  }
  ```

  ```shell curl theme={null}
  curl -s "https://api.pinecone.io/indexes" \
      -H "Api-Key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -H "X-Pinecone-Api-Version: 2025-10" \
      -d '{
          "name":  "docs-example",
          "dimension": 1536,
          "metric": "cosine",
          "spec": {
              "serverless": {
                 "cloud":"aws",
                 "region": "us-east-1"
              }
          }
      }'
  ```
</CodeGroup>

## Add headers to an HTTP request

All HTTP requests to Pinecone APIs must contain an `Api-Key` header that specifies a valid [API key](/guides/production/security-overview#api-keys) and must be encoded as JSON with the `Content-Type: application/json` header. For example:

```shell curl theme={null}
curl https://api.pinecone.io/indexes \
   -H "Content-Type: application/json" \
   -H "Api-Key: $PINECONE_API_KEY" \
  -H "X-Pinecone-Api-Version: 2025-10" \
   -d '{
         "name":  "docs-example",
         "dimension": 1536,
         "metric": "cosine",
         "spec": {
            "serverless": {
               "cloud":"aws",
               "region": "us-east-1"
            }
         }
      }'
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Initialization errors due to outdated SDKs">
    Older versions of Pinecone required you to initialize a client with an `init` method that takes both `api_key` and `environment` parameters, for example:

    <CodeGroup>
      ```python Python theme={null}
      # Legacy initialization
      import pinecone

      pc = pinecone.init(
          api_key="PINECONE_API_KEY",
          environment="PINECONE_ENVIRONMENT"
      )
      ```

      ```javascript JavaScript theme={null}
      // Legacy initialization
      import { Pinecone } from '@pinecone-database/pinecone';

      const pineconeClient = new PineconeClient();
      await pineconeClient.init({
          apiKey: 'PINECONE_API_KEY',
          environment: 'PINECONE_ENVIRONMENT',
      });
      ```
    </CodeGroup>

    In more recent versions of Pinecone, this has changed. Initialization no longer requires an `init` step, and cloud environment is defined for each index rather than an entire project. Client initialization now only requires an `api_key` parameter, for example:

    <CodeGroup>
      ```python Python theme={null}
      # New initialization
      from pinecone import Pinecone

      pc = Pinecone(api_key="YOUR_API_KEY")
      ```

      ```javascript JavaScript theme={null}
      // New initialization
      import { Pinecone } from '@pinecone-database/pinecone';

      const pc = new Pinecone({
          apiKey: 'YOUR_API_KEY' 
      });
      ```
    </CodeGroup>

    If you are receiving errors about initialization, upgrade your [Pinecone SDK](/reference/pinecone-sdks) to the latest version, for example:

    <CodeGroup>
      ```shell Python theme={null}
      # Upgrade Pinecone SDK
      pip install pinecone --upgrade
      ```

      ```shell JavaScript theme={null}
      # Upgrade Pinecone SDK
      npm install @pinecone-database/pinecone@latest
      ```
    </CodeGroup>

    Also, note that some third-party tutorials and examples still reference the older initialization method. In such cases, follow the example above and the examples throughout the Pinecone documentation instead.
  </Accordion>
</AccordionGroup>


# Pinecone Database limits
Source: https://docs.pinecone.io/reference/api/database-limits

Reference for Pinecone Database limits, covering upsert, query, fetch, delete, import, namespace, and rate limits for serverless indexes.

This page describes different types of limits for Pinecone Database.

<Note>
  **Looking for a specific limit?**

  * To compare monthly included usage by plan, start with [read units](#read-units-per-month-per-org), [write units](#write-units-per-month-per-org), and [model usage limits](#monthly-usage-limits).
  * If you received a `429` error, check [rate limits](#rate-limits), especially request-per-second limits for query, upsert, update, delete, fetch, and list.
  * For projects, users, indexes, namespaces, storage, backups, and collections, see [object limits](#object-limits).
  * For batch sizes, metadata filters, and identifier lengths, see [operation limits](#operation-limits) and [identifier limits](#identifier-limits).
</Note>

## Rate limits

Rate limits help protect your applications from misuse and maintain the health of our shared serverless infrastructure. These limits are designed to support typical production workloads while ensuring reliable performance for all users.

**Most rate limits can be adjusted upon request.** If you need higher limits to scale your application, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) with details about your use case. Pinecone is committed to supporting your growth and can often accommodate higher throughput requirements.

Rate limits vary based on [pricing plan](https://www.pinecone.io/pricing/) and apply to [serverless indexes](/guides/index-data/indexing-overview) only.

<Note>
  Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide.
</Note>

### Data plane operations: request-per-second limits

Pinecone enforces rate limits on the number of API requests per second at the namespace level for data plane operations (query, upsert, delete, and update). These limits provide protection against excessive request rates.

#### Affected operations

The following operations are subject to request-per-second rate limiting:

| Operation | Scope         | Limit |
| --------- | ------------- | ----- |
| Query     | Per namespace | 100   |
| Upsert    | Per namespace | 100   |
| Delete    | Per namespace | 100   |
| Update    | Per namespace | 100   |

#### Error response

When you exceed the request-per-second limit, you'll receive an HTTP `429 - TOO_MANY_REQUESTS` response. The error message indicates which operation exceeded the limit and includes the namespace name and limit value. See the individual limit sections below for specific error message formats.

#### How request-per-second limits work with limits on read and write units

Request-per-second limits are enforced in addition to existing read unit and write unit limits. Requests must not exceed any applicable limits:

* Index-level limits - read and write unit limits, per index
* Namespace-level limits - read and write unit limits, per namespace
* Request-per-second limits - requests per second, per namespace

If any limit is exceeded, the request fails with a 429 error.

#### Recommendations

If you're hitting request-per-second limits:

1. Implement retry logic. Use exponential backoff to handle rate limit errors gracefully. See [Error Handling Guide](/guides/production/error-handling#implement-retry-logic).
2. Pace your requests. Add client-side rate limiting to stay under limits.
3. Consider [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes), which don't have request-per-second limits and provide dedicated capacity for high-throughput workloads.
4. If you need higher limits, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) with details about your use case.

### All rate limits

#### Monthly usage limits

| Metric                                                                        | Starter plan   | Builder plan   | Standard plan  | Enterprise plan |
| :---------------------------------------------------------------------------- | :------------- | :------------- | :------------- | :-------------- |
| [Read units per month per org](#read-units-per-month-per-org)                 | 1,000,000      | 2,000,000      | Unlimited      | Unlimited       |
| [Write units per month per org](#write-units-per-month-per-org)               | 2,000,000      | 5,000,000      | Unlimited      | Unlimited       |
| [Embedding tokens per month per model](#embedding-tokens-per-month-per-model) | 5,000,000      | 10,000,000     | Unlimited      | Unlimited       |
| [Rerank requests per month per model](#rerank-requests-per-month-per-model)   | Model-specific | Model-specific | Model-specific | Model-specific  |

#### Data operation throughput limits

| Metric                                                                                                        | Starter plan | Builder plan | Standard plan | Enterprise plan |
| :------------------------------------------------------------------------------------------------------------ | :----------- | :----------- | :------------ | :-------------- |
| [Upsert size per second per namespace](#upsert-size-per-second-per-namespace)                                 | 50 MB        | 50 MB        | 50 MB         | 50 MB           |
| [Query read units per second per index](#query-read-units-per-second-per-index)                               | 2,000        | 2,000        | 2,000         | 2,000           |
| [Query requests per second per namespace](#query-requests-per-second-per-namespace)                           | 100          | 100          | 100           | 100             |
| [Update records per second per namespace](#update-records-per-second-per-namespace)                           | 100          | 100          | 100           | 100             |
| [Update requests per second per namespace](#update-requests-per-second-per-namespace)                         | 100          | 100          | 100           | 100             |
| [Update by metadata requests per second per namespace](#update-by-metadata-requests-per-second-per-namespace) | 5            | 5            | 5             | 5               |
| [Update by metadata requests per second per index](#update-by-metadata-requests-per-second-per-index)         | 500          | 500          | 500           | 500             |
| [Upsert requests per second per namespace](#upsert-requests-per-second-per-namespace)                         | 100          | 100          | 100           | 100             |
| [Fetch requests per second per index](#fetch-requests-per-second-per-index)                                   | 100          | 100          | 100           | 100             |
| [List requests per second per index](#list-requests-per-second-per-index)                                     | 200          | 200          | 200           | 200             |
| [Describe index stats requests per second per index](#describe-index-stats-requests-per-second-per-index)     | 100          | 100          | 100           | 100             |
| [Delete requests per second per namespace](#delete-requests-per-second-per-namespace)                         | 100          | 100          | 100           | 100             |
| [Delete records per second per namespace](#delete-records-per-second-per-namespace)                           | 5,000        | 5,000        | 5,000         | 5,000           |
| [Delete records per second per index](#delete-records-per-second-per-index)                                   | 5,000        | 5,000        | 5,000         | 5,000           |
| [Delete by metadata requests per second per namespace](#delete-by-metadata-requests-per-second-per-namespace) | 5            | 5            | 5             | 5               |
| [Delete by metadata requests per second per index](#delete-by-metadata-requests-per-second-per-index)         | 500          | 500          | 500           | 500             |

#### Model throughput limits

| Metric                                                                          | Starter plan   | Builder plan   | Standard plan  | Enterprise plan |
| :------------------------------------------------------------------------------ | :------------- | :------------- | :------------- | :-------------- |
| [Embedding tokens per minute per model](#embedding-tokens-per-minute-per-model) | Model-specific | Model-specific | Model-specific | Model-specific  |
| [Rerank requests per minute per model](#rerank-requests-per-minute-per-model)   | Model-specific | Model-specific | Model-specific | Model-specific  |

### Read units per month per org

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 1,000,000    | 2,000,000    | Unlimited     | Unlimited       |

[Read units](/guides/manage-cost/understanding-cost#read-units) measure the compute, I/O, and network resources used by [fetch](/guides/manage-data/fetch-data), [query](/guides/search/search-overview), and [list](/guides/manage-data/list-record-ids) requests to serverless indexes. When you reach the monthly read unit limit for an organization, fetch, query, and list requests to serverless indexes in the organization will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached your read unit limit for the current month limit. 
  To continue reading data, upgrade your plan. 
  ```
</Accordion>

To continue reading from serverless indexes in the organization, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan).

To check how close you are to the monthly read unit limit for your organization, do the following:

1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects).
2. Select the project.
3. Select any index in the project.
4. Look under **Usage**.

<Note>
  Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide.
</Note>

### Write units per month per org

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 2,000,000    | 5,000,000    | Unlimited     | Unlimited       |

[Write units](/guides/manage-cost/understanding-cost#write-units) measure the storage and compute resources used by [upsert](/guides/index-data/upsert-data), [update](/guides/manage-data/update-data), and [delete](/guides/manage-data/delete-data) requests to serverless indexes. When you reach the monthly write unit limit for an organization, upsert, update, and delete requests to serverless indexes in the organization will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached your write unit limit for the current month. 
  To continue writing data, upgrade your plan.
  ```
</Accordion>

To continue writing data to serverless indexes in the organization, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan).

To check how close you are to the monthly write unit limit for your organization, do the following:

1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects).
2. Select the project.
3. Select any index in the project.
4. Look under **Usage**.

### Upsert size per second per namespace

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 50 MB        | 50 MB        | 50 MB         | 50 MB           |

When you reach the per second [upsert](/guides/index-data/upsert-data) size for a namespace in an index, additional upserts will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max upsert size limit per second for index <index name>. 
  Pace your upserts or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Query read units per second per index

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 2,000        | 2,000        | 2,000         | 2,000           |

Pinecone measures [query](/guides/search/search-overview) usage in [read units](/guides/manage-cost/understanding-cost#read-units). When you reach the per second limit for queries across all namespaces in an index, additional queries will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max query read units per second for index <index name>. 
  Pace your queries or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

To check how many read units a query consumes, [check the query response](/guides/manage-cost/monitor-usage-and-costs#read-units).

<Note>
  Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide.
</Note>

### Query requests per second per namespace

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 100          | 100          | 100           | 100             |

When you reach the per second [query](/guides/search/search-overview) limit for a namespace in an index, additional queries will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the query QPS limit for namespace {namespace_name} ({limit} QPS). Pace your queries,
  consider Dedicated Read Nodes for your index, or contact Pinecone Support
  (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

<Note>
  Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide.
</Note>

### Update records per second per namespace

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 100          | 100          | 100           | 100             |

When you reach the per second [update](/guides/manage-data/update-data) limit for a namespace in an index, additional updates will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max update records per second for namespace <namespace name>. 
  Pace your update requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Update requests per second per namespace

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 100          | 100          | 100           | 100             |

When you reach the per second [update](/guides/manage-data/update-data) request limit for a namespace in an index, additional update requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the update QPS limit for namespace {namespace_name} ({limit} QPS). Pace your update requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

<Tip>
  If you need to update most of the records in a large namespace, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) for help creating an export to enable a faster and more cost-effective approach.
</Tip>

### Update by metadata requests per second per namespace

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 5            | 5            | 5             | 5               |

When you reach the per second [update by metadata](/guides/manage-data/update-data#update-metadata-across-multiple-records) request limit for a namespace in an index, additional update by metadata requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max update by metadata requests per second for namespace <namespace name>. Pace your update by metadata requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Update by metadata requests per second per index

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 500          | 500          | 500           | 500             |

When you reach the per second [update by metadata](/guides/manage-data/update-data#update-metadata-across-multiple-records) request limit across all namespaces in an index, additional update by metadata requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max update by metadata requests per second for index <index name>. Pace your update by metadata requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Upsert requests per second per namespace

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 100          | 100          | 100           | 100             |

When you reach the per second [upsert](/guides/index-data/upsert-data) request limit for a namespace in an index, additional upsert requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the upsert QPS limit for namespace {namespace_name} ({limit} QPS). Pace your upsert requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Fetch requests per second per index

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 100          | 100          | 100           | 100             |

When you reach the per second [fetch](/guides/manage-data/fetch-data) limit across all namespaces in an index, additional fetch requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max fetch requests per second for index <index name>.
  Pace your fetch requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

<Note>
  Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide.
</Note>

### List requests per second per index

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 200          | 200          | 200           | 200             |

When you reach the per second [list](/guides/manage-data/list-record-ids) limit across all namespaces in an index, additional list requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max list requests per second for index <index name>.
  Pace your list requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

<Note>
  Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide.
</Note>

### Describe index stats requests per second per index

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 100          | 100          | 100           | 100             |

When you reach the per second [describe index stats](/reference/api/2024-10/data-plane/describeindexstats) limit across all namespaces in an index, additional describe index stats requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max describe_index_stats requests per second for index <index>. 
  Pace your describe_index_stats requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Delete requests per second per namespace

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 100          | 100          | 100           | 100             |

When you reach the per second [delete](/guides/manage-data/delete-data) request limit for a namespace in an index, additional delete requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the delete QPS limit for namespace {namespace_name} ({limit} QPS). Pace your delete requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Delete records per second per namespace

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 5000         | 5000         | 5000          | 5000            |

When you reach the per second [delete](/guides/manage-data/delete-data) limit for a namespace in an index, additional deletes will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max delete records per second for namespace <namespace name>. 
  Pace your delete requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Delete records per second per index

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 5000         | 5000         | 5000          | 5000            |

When you reach the per second [delete](/guides/manage-data/delete-data) limit across all namespaces in an index, additional deletes will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max delete records per second for index <index name>. 
  Pace your delete requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Delete by metadata requests per second per namespace

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 5            | 5            | 5             | 5               |

When you reach the per second [delete by metadata](/guides/manage-data/delete-data#delete-records-by-metadata) request limit for a namespace in an index, additional delete by metadata requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max delete by metadata requests per second for namespace <namespace name>. Pace your delete by metadata requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Delete by metadata requests per second per index

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 500          | 500          | 500           | 500             |

When you reach the per second [delete by metadata](/guides/manage-data/delete-data#delete-records-by-metadata) request limit across all namespaces in an index, additional delete by metadata requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max delete by metadata requests per second for index <index name>. Pace your delete by metadata requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Embedding tokens per minute per model

| Embedding model              | Input type | Starter plan | Builder plan | Standard plan | Enterprise plan |
| :--------------------------- | :--------- | :----------- | :----------- | :------------ | :-------------- |
| `llama-text-embed-v2`        | Passage    | 250,000      | 250,000      | 1,000,000     | 1,000,000       |
|                              | Query      | 50,000       | 50,000       | 250,000       | 250,000         |
| `multilingual-e5-large`      | Passage    | 250,000      | 250,000      | 1,000,000     | 1,000,000       |
|                              | Query      | 50,000       | 50,000       | 250,000       | 250,000         |
| `pinecone-sparse-english-v0` | Passage    | 250,000      | 250,000      | 3,000,000     | 3,000,000       |
|                              | Query      | 250,000      | 250,000      | 3,000,000     | 3,000,000       |

When you reach the per minute token limit for an [embedding model](/guides/index-data/create-an-index#embedding-models) hosted by Pinecone, additional embeddings will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max embedding tokens per minute (<limit>) model '<model name>'' and input type '<passage|query>' for the current project. 
  To increase this limit, upgrade your plan.
  ```
</Accordion>

To increase this limit, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). Otherwise, you can handle this limit by [implementing retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic).

### Embedding tokens per month per model

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 5,000,000    | 10,000,000   | Unlimited     | Unlimited       |

When you reach the monthly token limit for an [embedding model](/guides/index-data/create-an-index#embedding-models) hosted by Pinecone, additional embeddings will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the embedding token limit (<limit>) for model <model name> for the current month. 
  To continue using this model, upgrade your plan.
  ```
</Accordion>

To increase this limit, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan) or [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Rerank requests per minute per model

| Reranking model        | Starter plan  | Builder plan  | Standard plan | Enterprise plan |
| :--------------------- | :------------ | :------------ | :------------ | :-------------- |
| `cohere-rerank-4-fast` | Not available | Not available | 300           | 300             |
| `cohere-rerank-3.5`    | Not available | Not available | 300           | 300             |
| `bge-reranker-v2-m3`   | 60            | 60            | 60            | 60              |
| `pinecone-rerank-v0`   | 60            | Not available | 60            | 60              |

When you reach the per minute request limit for a [reranking model](/guides/search/rerank-results#reranking-models) hosted by Pinecone, additional reranking requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max rerank requests per minute (<limit>) for model '<model name>' for the current project. 
  To increase this limit, upgrade your plan.
  ```
</Accordion>

To increase this limit, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan).

### Rerank requests per month per model

| Reranking model        | Starter plan  | Builder plan  | Standard plan | Enterprise plan |
| :--------------------- | :------------ | :------------ | :------------ | :-------------- |
| `cohere-rerank-4-fast` | Not available | Not available | Unlimited     | Unlimited       |
| `cohere-rerank-3.5`    | Not available | Not available | Unlimited     | Unlimited       |
| `bge-reranker-v2-m3`   | 500           | 1,000         | Unlimited     | Unlimited       |
| `pinecone-rerank-v0`   | 500           | Not available | Unlimited     | Unlimited       |

When you reach the monthly request limit for a [reranking model](/guides/search/rerank-results#reranking-models) hosted by Pinecone, additional reranking requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the rerank request limit (<limit>) for model <model name> for the current month. 
  To continue using this model, upgrade your plan.
  ```
</Accordion>

To increase this limit, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan) or [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Inference requests per second or minute, per project

| Metric                        | Starter plan | Builder plan | Standard plan | Enterprise plan |
| :---------------------------- | :----------- | :----------- | :------------ | :-------------- |
| Inference requests per second | 100          | 100          | 100           | 100             |
| Inference requests per minute | 2000         | 2000         | 2000          | 2000            |

When you reach the per second or per minute request limit, inference requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max inference requests per second (<limit>) for the current project.
  ```
</Accordion>

<Note>
  This error indicates per second or per minute, as applicable.
</Note>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic).

## Object limits

Object limits are restrictions on the number or size of objects in Pinecone. Object limits vary based on [pricing plan](https://www.pinecone.io/pricing/).

| Metric                                                                         | Starter plan | Builder plan | Standard plan | Enterprise plan |
| :----------------------------------------------------------------------------- | :----------- | :----------- | :------------ | :-------------- |
| [Projects per organization](#projects-per-organization)                        | 1            | 5            | 20            | 100             |
| [Users per organization](#users-per-organization)                              | 2            | 5            | Unlimited     | Unlimited       |
| [Serverless indexes per project](#serverless-indexes-per-project) <sup>1</sup> | 5            | 10           | 20            | 200             |
| [Serverless index storage per org](#serverless-index-storage-per-org)          | 2 GB         | 10 GB        | N/A           | N/A             |
| [Namespaces per serverless index](#namespaces-per-serverless-index)            | 100          | 1,000        | 100,000       | 100,000         |
| [Serverless backups per project](#serverless-backups-per-project)              | N/A          | N/A          | 500           | 1000            |
| [Collections per project](#collections-per-project)                            | 100          | N/A          | N/A           | N/A             |

<sup>1 On the Starter plan, all serverless indexes must be in the `us-east-1` region of AWS. Builder, Standard, and Enterprise plans can create indexes in any [supported region](/guides/index-data/create-an-index#cloud-regions).</sup><br />

### Projects per organization

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 1            | 5            | 20            | 100             |

When you reach this quota for an organization, trying to [create projects](/guides/projects/create-a-project) will fail and return a `403 - QUOTA_EXCEEDED` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max projects allowed in organization <org name>. 
  To add more projects, upgrade your plan.
  ```
</Accordion>

To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan) or [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Users per organization

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 2            | 5            | Unlimited     | Unlimited       |

When you reach this quota for an organization, trying to add users to the organization will fail. To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan).

### Serverless indexes per project

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 5            | 10           | 20            | 200             |

When you reach this quota for a project, trying to [create serverless indexes](/guides/index-data/create-an-index#create-a-serverless-index) in the project will fail and return a `403 - QUOTA_EXCEEDED` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max serverless indexes allowed in project <project>. 
  Use namespaces to partition your data into logical groups, or upgrade your plan to add more serverless indexes.
  ```
</Accordion>

To stay under this quota, consider using [namespaces](/guides/index-data/create-an-index#namespaces) instead of creating multiple indexes. Namespaces let you partition your data into logical groups within a single index. This approach not only helps you stay within index limits, but can also improve query performance and lower costs by limiting searches to relevant data subsets.

To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan).

### Serverless index storage per org

<Note>This limit applies to organizations on the Starter and Builder plans only.</Note>

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 2 GB         | 10 GB        | N/A           | N/A             |

When you've reached this quota for an organization, updates and upserts into serverless indexes will fail and return a `403 - QUOTA_EXCEEDED` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max storage allowed for organization <org name>. 
  To update or upsert new data, delete records or upgrade your plan.
  ```
</Accordion>

To continue writing data into your serverless indexes, [delete records](/guides/manage-data/delete-data) to bring your organization under the limit or [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan).

### Namespaces per serverless index

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 100          | 1,000        | 100,000       | 100,000         |

When you reach this quota for a serverless index, trying to [upsert records into a new namespace](/guides/index-data/upsert-data) in the index will fail and return a `403 - QUOTA_EXCEEDED` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max namespaces allowed in serverless index <index name>. 
  To add more namespaces, upgrade your plan.
  ```
</Accordion>

To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan).

<Note>
  [Namespaces per serverless index](/reference/api/database-limits#namespaces-per-serverless-index) vary by plan. On the Standard and Enterprise plans, Pinecone can accommodate million-scale namespaces and beyond for specific use cases. If your application requires more than 100,000 namespaces, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).
</Note>

### Serverless backups per project

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| N/A          | N/A          | 500           | 1000            |

Backups are not available on the Starter or Builder plans. On the Standard and Enterprise plans, when you reach this quota for a project, trying to [create serverless backups](/guides/manage-data/back-up-an-index) in the project will fail and return a `403 - QUOTA_EXCEEDED` status with the following error:

<Accordion title="Error response">
  ```
  Backup failed to create. Quota for number of backups per index exceeded.
  ```
</Accordion>

### Collections per project

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 100          | N/A          | N/A           | N/A             |

When you reach this quota for a project, trying to [create collections](/guides/manage-data/back-up-an-index) in the project will fail and return a `403 - QUOTA_EXCEEDED` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max collections allowed in project <project name>. 
  To add more collections, upgrade your plan.
  ```
</Accordion>

To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan).

## Operation limits

Operation limits are restrictions on the size, number, or other characteristics of operations in Pinecone. Operation limits are fixed and do not vary based on pricing plan.

### Upsert limits

| Metric                                                             | Limit                                                         |
| :----------------------------------------------------------------- | :------------------------------------------------------------ |
| Max [batch size](/guides/index-data/upsert-data#upsert-in-batches) | 2 MB or 1000 records with vectors <br /> 96 records with text |
| Max documents per upsert request                                   | 1000                                                          |
| Max document upsert request size                                   | 2 MB                                                          |
| Max document size                                                  | 2 MB                                                          |
| Max `full_text_search` string fields per schema                    | 100                                                           |
| Max size per `full_text_search` string field                       | 100 KB                                                        |
| Max tokens per `full_text_search` string field                     | 10,000                                                        |
| Max bytes per token                                                | 256 bytes                                                     |
| Max filterable metadata size per document                          | 40 KB                                                         |
| Max length for a record ID                                         | 512 characters                                                |
| Max dimensionality for dense vectors                               | 20,000                                                        |
| Max non-zero values for sparse vectors                             | 2048                                                          |
| Max dimensionality for sparse vectors                              | 4.2 billion                                                   |

The 40 KB filterable metadata limit does not apply to `full_text_search` text fields.

### Import limits

<Note>
  If your import exceeds these limits, you'll get an error specifying the limit exceeded. See [Troubleshooting](/guides/index-data/import-data#troubleshooting) for details.
</Note>

| Metric                                        | Limit     |
| :-------------------------------------------- | :-------- |
| Max namespaces per import                     | 10,000    |
| Max total input data size (on-demand indexes) | 1 TB      |
| Max total input data size (DRN indexes)       | Unlimited |
| Max files per import                          | 100,000   |
| Max size per file                             | 10 GB     |

The total input data size limit does not apply to indexes with [dedicated read nodes](/guides/index-data/dedicated-read-nodes).

Bulk import supports indexes without a schema definition (Parquet files) and indexes with document schemas ([JSONL files](/guides/search/full-text-search#bulk-import)). Semantic-text (auto-embedded) fields are not yet supported in document schemas.

### Query limits

| Metric            | Limit  |
| :---------------- | :----- |
| Max `top_k` value | 10,000 |
| Max result size   | 4MB    |

The query result size is affected by the dimension of the dense vectors and whether or not dense vector values and metadata are included in the result.

<Tip>
  If a query fails due to exceeding the 4MB result size limit, choose a lower `top_k` value, or use `include_metadata=False` or `include_values=False` to exclude metadata or values from the result. For better performance, especially with higher `top_k` values, avoid including vector values unless you need them.
</Tip>

### Fetch limits

**Fetch by ID limits:**

| Metric                           | Limit |
| :------------------------------- | :---- |
| Max record IDs per fetch request | 1,000 |

**Fetch by metadata limits:**

| Metric                   | Limit                               |
| :----------------------- | :---------------------------------- |
| Max records per response | 10,000                              |
| Max response size        | 4 MB                                |
| Max request rate         | 5 requests per second per namespace |

To retrieve more than 10,000 matching records, paginate through results using the `paginationToken` parameter. See [Fetch records by metadata](/guides/manage-data/fetch-data#fetch-records-by-metadata).

### Delete limits

| Metric                            | Limit |
| :-------------------------------- | :---- |
| Max record IDs per delete request | 1,000 |

### Metadata filter limits

The following limits apply to [metadata filter expressions](/guides/search/filter-by-metadata#metadata-filter-expressions) used in query, delete, update, and fetch operations.

| Limit                                       | Value  | Description                                                                                                                                                                                                      |
| :------------------------------------------ | :----- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Maximum values per `$in` or `$nin` operator | 10,000 | Each `$in` or `$nin` operator accepts up to 10,000 values in its array. This limit applies per operator—if you have multiple `$in` operators in a single filter, each is independently limited to 10,000 values. |

When you exceed this limit, the request will fail and return a `400 - BAD_REQUEST` error.

#### Rationale

Large `$in` operators can impact query performance and cost. Filters with thousands of values increase request payload size and end-to-end latency. Additionally, using large filters typically indicates a shared namespace architecture, which increases query costs—queries scan the entire namespace regardless of filters.

#### Alternative approaches

If you need to filter by more than 10,000 values, consider these alternatives:

* **Use namespaces for tenant isolation**: Instead of filtering by tenant IDs within a single namespace, create separate namespaces for each tenant or tenant group. This can also reduce query costs. See [Design for multi-tenancy](/guides/index-data/data-modeling#design-for-multi-tenancy).
* **Use broader access control groups**: Instead of filtering by individual user IDs, filter by organization, project, or role. This reduces the number of values in your `$in` filter. See [Design for multi-tenancy](/guides/index-data/data-modeling#use-access-control-groups-instead-of-individual-ids).
* **Post-filter client-side**: Retrieve a larger top K without filtering (for example, top 1000), then filter results client-side.
* **Run multiple queries**: Split your filter into multiple queries with smaller `$in` operators and combine the results client-side.

<Tip>
  To avoid hitting this limit in production, validate the size of your `$in` and `$nin` arrays in your application code before making the request to Pinecone.
</Tip>

## Identifier limits

An identifier is a string of characters used to identify "named" [objects in Pinecone](/guides/get-started/concepts). The following Pinecone objects use strings as identifiers:

| Object                                                    | Field       | Max # characters | Allowed characters                                                                                                                        |
| --------------------------------------------------------- | ----------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| [Organization](/guides/get-started/concepts#organization) | `name`      | 512              | <ul><li>UTF-8 except `\0`</li><li>Cannot be empty</li></ul>                                                                               |
| [Project](/guides/get-started/concepts#project)           | `name`      | 512              | <ul><li>UTF-8 except `\0`</li><li>Cannot be empty</li></ul>                                                                               |
| [Index](/guides/get-started/concepts#index)               | `name`      | 45               | <ul><li>`a-z`, `0-9`, and `-`</li><li>Must be lowercase</li><li>Cannot start or end with `-`</li><li>Cannot be empty</li></ul>            |
| [Namespace](/guides/get-started/concepts#namespace)       | `namespace` | 512              | <ul><li>ASCII except `\0`</li><li>For the default namespace, use `""` (or `"__default__"`, in API versions `2025-04` and later)</li></ul> |
| [Record](/guides/get-started/concepts#record)             | `id`        | 512              | <ul><li>ASCII except `\0`</li><li>Cannot be empty</li></ul>                                                                               |


# Errors
Source: https://docs.pinecone.io/reference/api/errors

Pinecone REST API: Pinecone uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the range.

Pinecone uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the `2xx` range indicate success, codes in the `4xx` range indicate an error that failed given the information provided, and codes in the `5xx` range indicate an error with Pinecone's servers.

For guidance on handling errors in production, see [Error handling](/guides/production/error-handling).

## 200 - OK

The request succeeded.

## 201 - CREATED

The request succeeded and a new resource was created.

## 202 - NO CONTENT

The request succeeded, but there is no content to return.

## 400 - INVALID ARGUMENT

The request failed due to an invalid argument.

## 401 - UNAUTHENTICATED

The request failed due to a missing or invalid [API key](/guides/projects/understanding-projects#api-keys).

## 402 - PAYMENT REQUIRED

The request failed due to delinquent payment or account deactivation for non-payment. See [Account deactivation for non-payment](/guides/organizations/manage-billing/non-payment-account-deactivation).

## 403 - FORBIDDEN

The request failed due to an exceeded [quota](/reference/api/database-limits#object-limits) or [index deletion protection](/guides/manage-data/manage-indexes#configure-deletion-protection).

## 404 - NOT FOUND

The request failed because the resource was not found.

## 409 - ALREADY EXISTS

The request failed because the resource already exists.

## 412 - FAILED PRECONDITIONS

The request failed due to preconditions not being met. |

## 422 - UNPROCESSABLE ENTITY

The request failed because the server was unable to process the contained instructions.

## 429 - TOO MANY REQUESTS

The request was [rate-limited](/reference/api/database-limits#rate-limits). [Implement retry logic with exponential backoff](/guides/production/error-handling#handle-rate-limits-429) to handle this error.

## 500 - UNKNOWN

An internal server error occurred. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) to handle transient errors.

## 502 - BAD GATEWAY

The API gateway received an invalid response from a backend service. This is typically a temporary error. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) to handle transient errors.

## 503 - UNAVAILABLE

The server is currently unavailable. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) to handle transient errors.

## 504 - GATEWAY TIMEOUT

The API gateway did not receive a timely response from the backend server. This can occur due to slow requests or backend processing delays. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) to handle transient errors.


# API reference
Source: https://docs.pinecone.io/reference/api/introduction

Pinecone API reference overview for Database, Inference, and Admin endpoints with supported SDKs including Python, Node.js, Java, and Go.

Pinecone's APIs let you interact programmatically with your Pinecone account.

<Note>
  [SDK versions](/reference/pinecone-sdks#sdk-versions) are pinned to specific API versions.
</Note>

## Database

Use the Database API to store and query records in [Pinecone Database](/guides/get-started/quickstart).

The following Pinecone SDKs support the Database API:

<CardGroup>
  <Card title="CLI" icon="terminal" href="/reference/cli/overview" />

  <Card title="Python SDK" icon="python" href="/reference/sdks/python/overview" />

  <Card title="Node.js SDK" icon="node-js" href="/reference/sdks/node/overview" />

  <Card title="Java SDK" icon="java" href="/reference/sdks/java/overview" />

  <Card title="Go SDK" icon="golang" href="/reference/sdks/go/overview" />
</CardGroup>

## Inference

Use the Inference API to generate vector embeddings and rerank results using [embedding models](/guides/index-data/create-an-index#embedding-models) and [reranking models](/guides/search/rerank-results#reranking-models) hosted on Pinecone's infrastructure.

There are two ways to use the Inference API:

* As a standalone service, through the [Rerank documents](/reference/api/latest/inference/rerank) and [Generate vectors](/reference/api/latest/inference/generate-embeddings) endpoints.
* As an integrated part of database operations, through the [Create an index with integrated embedding](/reference/api/latest/control-plane/create_for_model), [Upsert text](/reference/api/latest/data-plane/upsert_records), and [Search with text](/reference/api/latest/data-plane/search_records) endpoints.

The following Pinecone SDKs support using the Inference API:

<CardGroup>
  <Card title="Python SDK" icon="python" href="/reference/sdks/python/overview" />

  <Card title="Node.js SDK" icon="node-js" href="/reference/sdks/node/overview" />

  <Card title="Java SDK" icon="java" href="/reference/sdks/java/overview" />

  <Card title="Go SDK" icon="golang" href="/reference/sdks/go/overview" />
</CardGroup>


# Known limitations
Source: https://docs.pinecone.io/reference/api/known-limitations

Known limitations and feature restrictions for Pinecone indexes, including upsert consistency, metadata rules, and serverless caveats.

This page describes known limitations and feature restrictions in Pinecone.

## General

* [Upserts](/guides/index-data/upsert-data)
  * Pinecone is eventually consistent, so there can be a slight delay before upserted records are available to query.

    After upserting records, use the [`describe_index_stats`](/reference/api/2024-10/data-plane/describeindexstats) operation to check if the current vector count matches the number of records you expect, although this method may not work for pod-based indexes with multiple replicas.
  * Only indexes using the [dotproduct distance metric](/guides/index-data/indexing-overview#dotproduct) support querying sparse-dense vectors.

    Upserting, updating, and fetching sparse-dense vectors in indexes with a different distance metric will succeed, but querying will return an error.
  * Indexes created before February 22, 2023 do not support sparse vectors.
* [Metadata](/guides/index-data/upsert-data#upsert-with-metadata-filters)
  * Null metadata values aren't supported. Instead of setting a key to `null`, remove the key from the metadata payload.
  * Nested JSON objects are not supported.

## Serverless indexes

Serverless indexes do not support the following features:

* [Filtering index statistics by metadata](/reference/api/2024-10/data-plane/describeindexstats)
* [Private endpoints](/guides/production/configure-private-endpoints)

  * This feature is available on AWS only.


# API versioning
Source: https://docs.pinecone.io/reference/api/versioning

Pinecone REST API: Pinecone's APIs are versioned to ensure that your applications continue to work as expected as the platform evolves.

Pinecone's APIs are versioned to ensure that your applications continue to work as expected as the platform evolves. Versions are named by release date in the format `YYYY-MM`, for example, `2025-10`.

## Release schedule

On a quarterly basis, Pinecone releases a new **stable** API version as well as a **release candidate** of the next stable version.

* **Stable:** Each stable version remains unchanged and supported for a minimum of 12 months. Since stable versions are released every 3 months, this means you have at least 9 months to test and migrate your app to the newest stable version before support for the previous version is removed.

* **Release candidate:** The release candidate gives you insight into the upcoming changes in the next stable version. It is available for approximately 3 months before the release of the stable version and can include new features, improvements, and [breaking changes](#breaking-changes).

Below is an example of Pinecone's release schedule:

<img />

<img />

## Specify an API version

<Warning>
  When using the API directly, it is important to specify an API version in your requests. If you don't, requests default to the oldest supported stable version. Once support for that version ends, your requests will default to the next oldest stable version, which could include breaking changes that require you to update your integration.
</Warning>

To specify an API version, set the `X-Pinecone-Api-Version` header to the version name.

For example, to use the latest stable version (`2026-04`) to describe an index, set the `X-Pinecone-Api-Version` header:

```shell curl theme={null}
PINECONE_API_KEY="YOUR_API_KEY"

curl -i -X GET "https://api.pinecone.io/indexes/movie-recommendations" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2026-04"
```

To use an older version, specify that version instead.

## SDK versions

Official [Pinecone SDKs](/reference/pinecone-sdks) provide convenient access to Pinecone APIs. SDK versions are pinned to specific API versions. When a new API version is released, a new version of the SDK is also released.

For the mapping between SDK and API versions, see [SDK versions](/reference/pinecone-sdks#sdk-versions).

## Breaking changes

Breaking changes are changes that can potentially break your integration with a Pinecone API. Breaking changes include:

* Removing an entire operation
* Removing or renaming a parameter
* Removing or renaming a response field
* Adding a new required parameter
* Making a previously optional parameter required
* Changing the type of a parameter or response field
* Removing enum values
* Adding a new validation rule to an existing parameter
* Changing authentication or authorization requirements

## Non-breaking changes

Non-breaking changes are additive and should not break your integration. Additive changes include:

* Adding an operation
* Adding an optional parameter
* Adding an optional request header
* Adding a response field
* Adding a response header
* Adding enum values

## Get updates

To ensure you always know about upcoming API changes, follow the [Release notes](/release-notes/).


# CLI authentication
Source: https://docs.pinecone.io/reference/cli/authentication

Authenticate the Pinecone CLI using user login, service accounts, or API keys, including auth priority and Admin API access rules.

This document describes how to authenticate the Pinecone CLI to manage your Pinecone resources.

## Authentication methods

| Method                              | Admin API | Control/data plane | Best for                         |
| ----------------------------------- | --------- | ------------------ | -------------------------------- |
| [User login](#user-login)           | ✅         | ✅                  | Interactive use                  |
| [Service account](#service-account) | ✅         | ✅                  | Automation with Admin API access |
| [API key](#api-key)                 | ❌         | ✅                  | Simple automation, CI/CD         |

### User login

Authenticate through a web browser. The token refreshes automatically and stays valid for up to 120 days (re-auth required after 30 days of inactivity).

```bash theme={null}
pc auth login
```

The CLI auto-targets your default organization and its first project. Change with `pc target -o "my-org" -p "my-project"`.

### Service account

Authenticate with credentials from a [service account](/guides/organizations/manage-service-accounts).

```bash theme={null}
pc auth configure --client-id "ID" --client-secret "SECRET"

# Or via environment variables
export PINECONE_CLIENT_ID="your-client-id"
export PINECONE_CLIENT_SECRET="your-client-secret"
```

The CLI auto-targets the service account's organization. For projects: auto-selects if one exists, prompts if multiple exist, or set manually with `pc target -p "my-project"`.

### API key

Authenticate with an [API key](/guides/projects/manage-api-keys). API keys can't access the Admin API.

```bash theme={null}
pc auth configure --api-key "YOUR_API_KEY"

# Or via environment variable
export PINECONE_API_KEY="your-api-key"
```

<Warning>
  API keys are scoped to a specific project. When set, control/data plane operations use the **key's project**, ignoring any [target context](/reference/cli/target-context) you've set.
</Warning>

## Auth priority

When multiple credentials exist, the CLI chooses based on operation type. Within each credential type, environment variables take precedence over stored configuration.

**Control/data plane operations:**

1. API key
2. User login token (via [managed keys](#managed-keys))
3. Service account (via [managed keys](#managed-keys))

**Admin API operations:**

1. User login token
2. Service account

<Note>
  User login and service account are mutually exclusive when configured via CLI commands—each clears the other. However, service account env vars don't clear a stored user login token.
</Note>

**Example scenarios:**

* If `PINECONE_API_KEY` is set, the CLI uses it for control/data plane operations, regardless of any stored API key.
* If you're logged in via `pc auth login` and also have `PINECONE_CLIENT_ID`/`PINECONE_CLIENT_SECRET` set, the user login token is used for everything—the service account env vars are ignored.
* If you have an API key configured and are also logged in, the API key is used for control/data plane operations, but user login is used for Admin API operations (since API keys can't access Admin API).

## Managed keys

When using user login or service account (without a default API key), the CLI automatically creates and manages API keys for control/data plane operations. This happens transparently on first use.

* **Stored locally:** `~/.config/pinecone/secrets.yaml` (permissions 0600)
* **Stored remotely:** Visible in console as `pinecone-cli-{id}` with origin `cli_created`

```bash theme={null}
# List locally tracked managed keys
pc auth local-keys list

# Delete managed keys (local + remote)
pc auth local-keys prune

# Delete only CLI-created managed keys
pc auth local-keys prune --origin cli

# Delete only user-created managed keys
pc auth local-keys prune --origin user

# Delete a specific API key by ID
pc api-key delete --id "KEY_ID"
```

<Note>
  When you run `pc api-key create --store` for a project that already has a CLI-created managed key, the CLI automatically deletes the old remote key before storing the new one.
</Note>

## Logging out

```bash theme={null}
pc auth logout
```

Clears all local auth data: tokens, credentials, API keys, managed keys, and [target context](/reference/cli/target-context).

<Note>
  `pc auth logout` doesn't delete managed keys from Pinecone's servers. Run `pc auth local-keys prune` first for full cleanup.
</Note>

## Local storage

Auth data is stored in `~/.config/pinecone/` with 0600 permissions:

| File           | Contents                                                         |
| -------------- | ---------------------------------------------------------------- |
| `secrets.yaml` | OAuth token, service account credentials, API keys, managed keys |
| `state.yaml`   | Target org/project                                               |
| `config.yaml`  | CLI settings (color, environment)                                |

## Check status

```bash theme={null}
pc auth status
```

Shows your current authentication method, target organization and project, token expiration (for user login), and environment configuration.


# CLI command reference
Source: https://docs.pinecone.io/reference/cli/command-reference

Complete Pinecone CLI command reference covering syntax, subcommands, flags, help output, and exit codes for auth, index, and project.

This document provides a complete reference for all Pinecone CLI commands.

## Command structure

The Pinecone CLI uses a hierarchical command structure. Each command consists of a primary command followed by one or more subcommands and optional flags.

```bash theme={null}
pc <command> <subcommand> [flags]
pc <command> <subcommand> <subcommand> [flags]
```

For example:

```bash theme={null}
# Top-level command with flags
pc target -o "organization-name" -p "project-name"

# Command (index) and subcommand (list)
pc index list

# Command (index) and subcommand (create) with flags
pc index create \
  --name my-index \
  --dimension 1536 \
  --metric cosine \
  --cloud aws \
  --region us-east-1

# Command (auth) and nested subcommands (local-keys prune) with flags
pc auth local-keys prune --id proj-abc123 --skip-confirmation
```

## Getting help

The CLI provides help for commands at every level:

```bash theme={null}
# top-level help
pc --help
pc -h

# command help
pc auth --help
pc index --help
pc project --help

# subcommmand help
pc index create --help
pc project create --help
pc auth configure --help

# nested subcommand help
pc auth local-keys prune --help
```

## Exit codes

All commands return exit code `0` for success and `1` for error.

## Available commands

This section describes all commands offered by the Pinecone CLI.

### Top-level commands

<AccordionGroup>
  <Accordion title="pc login (Authenticate via user login)">
    **Description**

    Authenticate via a web browser. After login, set a [target org and project](/reference/cli/target-context) with `pc target` before accessing data. This command defaults to an initial organization and project to which
    you have access (these values display in the terminal), but you can change them with `pc target`.

    **Usage**

    ```bash theme={null}
    pc login
    ```

    **Flags**

    None

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Log in via browser
    pc login

    # Then set target context
    pc target -o "my-org" -p "my-project"
    ```

    <Note>
      This is an alias for `pc auth login`. Both commands perform the same operation.
    </Note>
  </Accordion>

  <Accordion title="pc logout (Clear credentials / log out)">
    **Description**

    Clears all authentication data from local storage, including:

    * User login token
    * Service account credentials (client ID and secret)
    * Default (manually specified) API key
    * Locally managed keys (for all projects)
    * Target organization and project context

    **Usage**

    ```bash theme={null}
    pc logout
    ```

    **Flags**

    None

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Clear all credentials and context
    pc logout
    ```

    <Note>
      This is an alias for `pc auth logout`. Both commands perform the same operation. Does not delete managed API keys from Pinecone's servers. Run `pc auth local-keys prune` before logging out to fully clean up.
    </Note>
  </Accordion>

  <Accordion title="pc target (Set target organization and project)">
    **Description**

    Set the target organization and project for the CLI. Supports interactive organization and project selection or direct specification via flags.  For details, see [CLI target context](/reference/cli/target-context).

    **Usage**

    ```bash theme={null}
    pc target [flags]
    ```

    **Flags**

    | Long flag           | Short flag | Description                    |
    | :------------------ | :--------- | :----------------------------- |
    | `--clear`           |            | Clear target context           |
    | `--json`            | `-j`       | Output in JSON format          |
    | `--org`             | `-o`       | Organization name              |
    | `--organization-id` |            | Organization ID                |
    | `--project`         | `-p`       | Project name                   |
    | `--project-id`      |            | Project ID                     |
    | `--show`            | `-s`       | Display current target context |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Interactive targeting after login
    pc login
    pc target

    # Set specific organization and project
    pc target -o "my-org" -p "my-project"

    # Show current context
    pc target --show

    # Clear all context
    pc target --clear
    ```
  </Accordion>

  <Accordion title="pc version (Show CLI version)">
    **Description**

    Displays version information for the CLI, including the version number, commit SHA, and build date.

    **Usage**

    ```bash theme={null}
    pc version
    ```

    **Flags**

    None

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Display version information
    pc version
    ```
  </Accordion>

  <Accordion title="pc whoami (Show current user)">
    **Description**

    Displays information about the currently authenticated user. To use this command, you must be authenticated via user login.

    **Usage**

    ```bash theme={null}
    pc whoami
    ```

    **Flags**

    None

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    pc whoami
    ```

    <Note>
      This is an alias for `pc auth whoami`. Both commands perform the same operation.
    </Note>
  </Accordion>
</AccordionGroup>

### Authentication

<AccordionGroup>
  <Accordion title="pc auth clear (Clear specific credentials)">
    **Description**

    Selectively clears specific authentication data without affecting other credentials. At least one flag is required.

    **Usage**

    ```bash theme={null}
    pc auth clear [flags]
    ```

    **Flags**

    | Long flag           | Short flag | Description                                         |
    | :------------------ | :--------- | :-------------------------------------------------- |
    | `--api-key`         |            | Clear only the default (manually specified) API key |
    | `--service-account` |            | Clear only service account credentials              |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Clear only the default (manually specified) API key
    pc auth clear --api-key
    pc auth status

    # Clear service account
    pc auth clear --service-account
    ```

    <Note>
      More surgical than `pc auth logout`. Does not clear user login token or managed keys. For those, use `pc auth logout` or `pc auth local-keys prune`.
    </Note>
  </Accordion>

  <Accordion title="pc auth configure (Configure service account or API key)">
    **Description**

    Configures service account credentials or a default (manually specified) API key.

    Service accounts automatically target the organization and prompt for project selection, unless there is only one project. A default API key overrides any previously specified target organization/project context. When setting a service account, this operation clears the user login token, if one exists.
    For details, see [CLI target context](/reference/cli/target-context).

    **Usage**

    ```bash theme={null}
    pc auth configure [flags]
    ```

    **Flags**

    | Long flag               | Short flag | Description                                          |
    | :---------------------- | :--------- | :--------------------------------------------------- |
    | `--api-key`             |            | Default API key to use for authentication            |
    | `--client-id`           |            | Service account client ID                            |
    | `--client-secret`       |            | Service account client secret                        |
    | `--client-secret-stdin` |            | Read client secret from stdin                        |
    | `--json`                | `-j`       | Output in JSON format                                |
    | `--project-id`          | `-p`       | Target project ID (optional, interactive if omitted) |
    | `--prompt-if-missing`   |            | Prompt for missing credentials                       |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Service account setup (auto-targets org and prompts for project)
    pc auth configure --client-id my-id --client-secret my-secret

    # Service account with specific project
    pc auth configure \
      --client-id my-id \
      --client-secret my-secret \
      -p proj-123

    # Default API key (overrides any target context)
    pc auth configure --api-key pcsk_abc123
    ```

    <Note>
      `pc auth configure --api-key "YOUR_API_KEY"` does the same thing as `pc config set-api-key "YOUR_API_KEY"`. To learn about targeting a project after authenticating with a service account, see [CLI target context](/reference/cli/target-context).
    </Note>
  </Accordion>

  <Accordion title="pc auth local-keys list (List managed keys)">
    **Description**

    Displays all [managed API keys](/reference/cli/authentication#managed-keys) stored locally by the CLI, with various details.

    **Usage**

    ```bash theme={null}
    pc auth local-keys list [flags]
    ```

    **Flags**

    | Long flag  | Short flag | Description                                |
    | :--------- | :--------- | :----------------------------------------- |
    | `--json`   | `-j`       | Output in JSON format                      |
    | `--reveal` |            | Show the actual API key values (sensitive) |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # List all locally managed keys
    pc auth local-keys list

    # Show key values
    pc auth local-keys list --reveal

    # After storing a key
    pc api-key create -n "my-key" --store
    pc auth local-keys list
    ```
  </Accordion>

  <Accordion title="pc auth local-keys prune (Delete managed keys)">
    **Description**

    Deletes locally stored [managed API keys](/reference/cli/authentication#managed-keys) from local storage and Pinecone's servers. Filters by origin (`cli`/`user`/`all`) or project ID.

    **Usage**

    ```bash theme={null}
    pc auth local-keys prune [flags]
    ```

    **Flags**

    | Long flag             | Short flag | Description                                                 |
    | :-------------------- | :--------- | :---------------------------------------------------------- |
    | `--dry-run`           |            | Preview deletions without applying                          |
    | `--id`                |            | Prune keys for specific project ID only                     |
    | `--json`              | `-j`       | Output in JSON format                                       |
    | `--origin`            | `-o`       | Filter by origin - `cli`, `user`, or `all` (default: `all`) |
    | `--skip-confirmation` |            | Skip confirmation prompt                                    |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Preview deletions
    pc auth local-keys prune --dry-run

    # Delete CLI-created keys only
    pc auth local-keys prune -o cli --skip-confirmation

    # Delete for specific project
    pc auth local-keys prune --id proj-abc123

    # Before/after check
    pc auth local-keys list
    pc auth local-keys prune -o cli
    pc auth local-keys list
    ```

    <Note>
      This deletes keys from both local storage and Pinecone servers. Use `--dry-run` to preview before committing.
    </Note>
  </Accordion>

  <Accordion title="pc auth login (Authenticate via user login)">
    **Description**

    Authenticate via user login in the web browser. After login, [set a target org and project](/reference/cli/target-context).

    **Usage**

    ```bash theme={null}
    pc auth login
    pc login  # shorthand
    ```

    **Flags**

    None

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Login and set target
    pc auth login
    pc target -o "my-org" -p "my-project"
    pc index list
    ```

    <Note>
      Tokens refresh automatically and remain valid for up to 120 days. If you're inactive for more than 30 days, you must re-authenticate. Logging in clears any existing service account credentials. This command does the same thing as `pc login`.
    </Note>
  </Accordion>

  <Accordion title="pc auth logout (Clear authentication credentials)">
    **Description**

    Clears all authentication data from local storage, including:

    * User login token
    * Service account credentials (client ID and secret)
    * Default (manually specified) API key
    * Locally managed keys (for all projects)
    * Target organization and project context

    **Usage**

    ```bash theme={null}
    pc auth logout
    ```

    **Flags**

    None

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Clear all credentials and context
    pc auth logout
    ```

    <Note>
      This command does the same thing as `pc logout`. Does not delete managed API keys from Pinecone's servers. Run `pc auth local-keys prune` before logging out to fully clean up.
    </Note>
  </Accordion>

  <Accordion title="pc auth status (Show authentication status)">
    **Description**

    Shows details about all configured authentication methods.

    **Usage**

    ```bash theme={null}
    pc auth status [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description           |
    | :-------- | :--------- | :-------------------- |
    | `--json`  | `-j`       | Output in JSON format |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Check status after login
    pc auth login
    pc auth status

    # JSON output for scripting
    pc auth status --json
    ```
  </Accordion>

  <Accordion title="pc auth whoami (Show current user information)">
    **Description**

    Displays information about the currently authenticated user. To use this command, you must be authenticated via user login.

    **Usage**

    ```bash theme={null}
    pc auth whoami
    ```

    **Flags**

    None

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    pc auth whoami
    ```

    <Note>
      This command does the same thing as `pc whoami`.
    </Note>
  </Accordion>
</AccordionGroup>

### Indexes

<AccordionGroup>
  <Accordion title="pc index configure (Update index configuration)">
    **Description**

    Modifies the configuration of an existing index.

    **Usage**

    ```bash theme={null}
    pc index configure [flags]
    ```

    **Flags**

    | Long flag                | Short flag | Description                                                     |
    | :----------------------- | :--------- | :-------------------------------------------------------------- |
    | `--index-name`           | `-i`       | Name of index to configure (required)                           |
    | `--deletion-protection`  |            | Enable or disable deletion protection - `enabled` or `disabled` |
    | `--tags`                 |            | Custom user tags (key=value pairs)                              |
    | `--json`                 | `-j`       | Output in JSON format                                           |
    | **Dedicated read nodes** |            |                                                                 |
    | `--read-mode`            |            | Read capacity mode - `ondemand` or `dedicated`                  |
    | `--read-node-type`       |            | Node type for dedicated read - `b1` or `t1`                     |
    | `--read-shards`          |            | Number of shards for dedicated read capacity                    |
    | `--read-replicas`        |            | Number of replicas for dedicated read capacity                  |
    | **Integrated embedding** |            |                                                                 |
    | `--model`                |            | Embedding model name                                            |
    | `--field-map`            |            | Field mapping for embedding (key=value pairs)                   |
    | `--read-parameters`      |            | Read parameters for embedding model (key=value pairs)           |
    | `--write-parameters`     |            | Write parameters for embedding model (key=value pairs)          |
    | **Pods**                 |            |                                                                 |
    | `--pod-type`             | `-t`       | Type of pod to use; can only upgrade when configuring           |
    | `--replicas`             | `-r`       | Number of replicas of the index to configure                    |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Enable deletion protection
    pc index configure --index-name my-index --deletion-protection enabled

    # Add tags
    pc index configure --index-name my-index --tags environment=production,team=ml

    # Switch to dedicated read capacity
    pc index configure --index-name my-index \
      --read-mode dedicated \
      --read-node-type b1 \
      --read-shards 2 \
      --read-replicas 2

    # Verify changes
    pc index describe --index-name my-index
    ```

    <Note>
      Configuration changes may take some time to take effect.
    </Note>
  </Accordion>

  <Accordion title="pc index create (Create a new index)">
    **Description**

    Creates a new index in your Pinecone project. Supports serverless, pod-based, integrated (with embedding model), and BYOC (Bring Your Own Cloud) index types.

    **Usage**

    ```bash theme={null}
    pc index create [flags]
    ```

    **Flags**

    | Long flag                | Short flag | Description                                                                    |
    | :----------------------- | :--------- | :----------------------------------------------------------------------------- |
    | `--name`                 | `-n`       | Index name (required)                                                          |
    | `--dimension`            | `-d`       | Vector dimension (required for standard indexes, optional for integrated)      |
    | `--metric`               | `-m`       | Similarity metric - `cosine`, `euclidean`, or `dotproduct` (default: `cosine`) |
    | `--cloud`                | `-c`       | Cloud provider - `aws`, `gcp`, or `azure`                                      |
    | `--region`               | `-r`       | Cloud region                                                                   |
    | `--vector-type`          | `-v`       | Vector type - `dense` or `sparse` (serverless only)                            |
    | `--source-collection`    |            | Name of the source collection from which to create the index                   |
    | `--schema`               |            | Metadata schema to control which fields are indexed (comma-separated)          |
    | `--deletion-protection`  |            | Deletion protection - `enabled` or `disabled`                                  |
    | `--tags`                 |            | Custom user tags (key=value pairs)                                             |
    | `--json`                 | `-j`       | Output in JSON format                                                          |
    | **Integrated indexes**   |            |                                                                                |
    | `--model`                |            | Integrated embedding model name                                                |
    | `--field-map`            |            | Field mapping for integrated embedding (key=value pairs)                       |
    | `--read-parameters`      |            | Read parameters for embedding model (key=value pairs)                          |
    | `--write-parameters`     |            | Write parameters for embedding model (key=value pairs)                         |
    | **BYOC indexes**         |            |                                                                                |
    | `--byoc-environment`     |            | BYOC environment to use for the index                                          |
    | **Dedicated read nodes** |            |                                                                                |
    | `--read-mode`            |            | Read capacity mode - `ondemand` or `dedicated` (default: `ondemand`)           |
    | `--read-node-type`       |            | Node type for dedicated read - `b1` or `t1`                                    |
    | `--read-shards`          |            | Number of shards (each shard provides 250 GB storage)                          |
    | `--read-replicas`        |            | Number of replicas for higher throughput                                       |
    | **Pod-based indexes**    |            |                                                                                |
    | `--environment`          |            | Environment of the index to create (for example, `us-east-1-aws`)              |
    | `--pod-type`             |            | Type of pod to use (for example, `p1.x1`, `s1.x2`)                             |
    | `--shards`               |            | Number of shards (default: `1`)                                                |
    | `--replicas`             |            | Number of replicas (default: `1`)                                              |
    | `--metadata-config`      |            | Comma-separated list of metadata fields to index for search                    |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Create serverless index
    pc index create -n my-index -d 1536 -m cosine -c aws -r us-east-1

    # Create sparse vector index
    pc index create -n sparse-index -m dotproduct -c aws -r us-east-1 --vector-type sparse

    # With integrated embedding model
    pc index create \
      -n my-index \
      -m cosine \
      -c aws \
      -r us-east-1 \
      --model multilingual-e5-large \
      --field-map text=chunk_text

    # With dedicated read capacity
    pc index create \
      -n my-index \
      -d 1536 \
      -m cosine \
      -c aws \
      -r us-east-1 \
      --read-mode dedicated \
      --read-node-type b1 \
      --read-shards 2 \
      --read-replicas 2

    # With deletion protection
    pc index create \
      -n my-index \
      -d 1536 \
      -m cosine \
      -c aws \
      -r us-west-2 \
      --deletion-protection enabled

    # From collection
    pc index create \
      -n my-index \
      -d 1536 \
      -m cosine \
      -c aws \
      -r eu-west-1 \
      --source-collection my-collection

    # Create pod-based index
    pc index create \
      -n my-index \
      -d 1536 \
      -m cosine \
      --environment us-east-1-aws \
      --pod-type p1.x1 \
      --shards 1 \
      --replicas 1
    ```

    <Note>
      For a list of valid regions for a serverless index, see [Create a serverless index](/guides/index-data/create-an-index).
    </Note>
  </Accordion>

  <Accordion title="pc index delete (Delete an index)">
    **Description**

    Permanently deletes an index and all its data. This operation cannot be undone.

    **Usage**

    ```bash theme={null}
    pc index delete [flags]
    ```

    **Flags**

    | Long flag             | Short flag | Description                                                |
    | :-------------------- | :--------- | :--------------------------------------------------------- |
    | `--index-name`        | `-i`       | Name of index to delete (required)                         |
    | `--skip-confirmation` |            | Skip the deletion confirmation prompt                      |
    | `--json`              | `-j`       | Output in JSON format (also skips the confirmation prompt) |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Delete an index (prompts for confirmation)
    pc index delete --index-name my-index

    # Skip the confirmation prompt
    pc index delete --index-name my-index --skip-confirmation

    # List before and after
    pc index list
    pc index delete --index-name test-index --skip-confirmation
    pc index list
    ```

    <Note>
      This command prompts for confirmation before deleting. Pass `--skip-confirmation` (or `--json`) to bypass the prompt in non-interactive contexts.
    </Note>
  </Accordion>

  <Accordion title="pc index describe (Show index details)">
    **Description**

    Displays detailed configuration and status information for a specific index.

    **Usage**

    ```bash theme={null}
    pc index describe [flags]
    ```

    **Flags**

    | Long flag      | Short flag | Description           |
    | :------------- | :--------- | :-------------------- |
    | `--index-name` | `-i`       | Index name (required) |
    | `--json`       | `-j`       | Output in JSON format |

    The `--name`/`-n` flag is a deprecated alias for `--index-name`/`-i`.

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Describe an index
    pc index describe -i my-index

    # JSON output
    pc index describe -i my-index -j

    # Check newly created index
    pc index create -n test-index -d 1536 -m cosine -c aws -r us-east-1
    pc index describe -i test-index
    ```
  </Accordion>

  <Accordion title="pc index stats (Show index statistics)">
    **Description**

    Displays statistics for an index, including total vector count and namespace breakdown. Optionally filter results with a metadata filter.

    **Usage**

    ```bash theme={null}
    pc index stats [flags]
    ```

    **Flags**

    | Long flag      | Short flag | Description                                                    |
    | :------------- | :--------- | :------------------------------------------------------------- |
    | `--index-name` | `-i`       | Index name (required)                                          |
    | `--filter`     | `-f`       | Metadata filter (inline JSON, `./path.json`, or `-` for stdin) |
    | `--json`       | `-j`       | Output in JSON format                                          |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Get stats for an index
    pc index stats -i my-index

    # Get stats with a metadata filter
    pc index stats -i my-index --filter '{"genre":{"$eq":"rock"}}'

    # Filter from file
    pc index stats -i my-index --filter ./filter.json

    # JSON output
    pc index stats -i my-index -j
    ```
  </Accordion>

  <Accordion title="pc index list (List all indexes)">
    **Description**

    Displays all indexes in your current target project, including various details.

    **Usage**

    ```bash theme={null}
    pc index list [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description                                         |
    | :-------- | :--------- | :-------------------------------------------------- |
    | `--json`  | `-j`       | Output in JSON format (includes full index details) |
    | `--wide`  | `-w`       | Show additional columns (host, embed, tags)         |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # List all indexes
    pc index list

    # Show additional details
    pc index list --wide

    # JSON output for scripting
    pc index list -j

    # After creating indexes
    pc index create -n test-1 -d 768 -m cosine -c aws -r us-east-1
    pc index list
    ```
  </Accordion>
</AccordionGroup>

### Namespaces

<AccordionGroup>
  <Accordion title="pc index namespace create (Create a namespace)">
    **Description**

    Creates a new namespace within an index. Namespaces allow you to partition vectors within an index.

    **Usage**

    ```bash theme={null}
    pc index namespace create [flags]
    ```

    **Flags**

    | Long flag      | Short flag | Description                                         |
    | :------------- | :--------- | :-------------------------------------------------- |
    | `--index-name` | `-i`       | Index name (required)                               |
    | `--name`       |            | Namespace name (required)                           |
    | `--schema`     |            | Metadata schema for the namespace (comma-separated) |
    | `--json`       | `-j`       | Output in JSON format                               |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Create a namespace
    pc index namespace create -i my-index --name tenant-a

    # Create with metadata schema (comma-separated list of filterable metadata fields)
    pc index namespace create -i my-index --name tenant-b --schema "category,brand"

    # JSON output
    pc index namespace create -i my-index --name tenant-c -j
    ```
  </Accordion>

  <Accordion title="pc index namespace delete (Delete a namespace)">
    **Description**

    Deletes a namespace and all its vectors from an index. This operation cannot be undone.

    **Usage**

    ```bash theme={null}
    pc index namespace delete [flags]
    ```

    **Flags**

    | Long flag             | Short flag | Description                                                            |
    | :-------------------- | :--------- | :--------------------------------------------------------------------- |
    | `--index-name`        | `-i`       | Index name (required)                                                  |
    | `--name`              |            | Namespace name (required); use `__default__` for the default namespace |
    | `--skip-confirmation` |            | Skip the deletion confirmation prompt                                  |
    | `--json`              | `-j`       | Output in JSON format (also skips the confirmation prompt)             |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Delete a namespace (prompts for confirmation)
    pc index namespace delete -i my-index --name tenant-a

    # Delete the default namespace
    pc index namespace delete -i my-index --name __default__

    # Skip the confirmation prompt
    pc index namespace delete -i my-index --name tenant-a --skip-confirmation
    ```

    <Warning>
      Deleting a namespace removes all vectors in that namespace. This operation cannot be undone.
    </Warning>
  </Accordion>

  <Accordion title="pc index namespace describe (Show namespace details)">
    **Description**

    Displays detailed information about a specific namespace, including record count and schema configuration.

    **Usage**

    ```bash theme={null}
    pc index namespace describe [flags]
    ```

    **Flags**

    | Long flag      | Short flag | Description                                                            |
    | :------------- | :--------- | :--------------------------------------------------------------------- |
    | `--index-name` | `-i`       | Index name (required)                                                  |
    | `--name`       |            | Namespace name (required); use `__default__` for the default namespace |
    | `--json`       | `-j`       | Output in JSON format                                                  |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Describe a namespace
    pc index namespace describe -i my-index --name tenant-a

    # Describe the default namespace
    pc index namespace describe -i my-index --name __default__

    # JSON output
    pc index namespace describe -i my-index --name tenant-a -j
    ```
  </Accordion>

  <Accordion title="pc index namespace list (List namespaces)">
    **Description**

    Lists all namespaces within an index, including vector counts.

    **Usage**

    ```bash theme={null}
    pc index namespace list [flags]
    ```

    **Flags**

    | Long flag            | Short flag | Description                    |
    | :------------------- | :--------- | :----------------------------- |
    | `--index-name`       | `-i`       | Index name (required)          |
    | `--limit`            | `-l`       | Maximum number of results      |
    | `--pagination-token` | `-p`       | Pagination token for next page |
    | `--prefix`           |            | Filter namespaces by prefix    |
    | `--json`             | `-j`       | Output in JSON format          |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # List all namespaces
    pc index namespace list -i my-index

    # Filter by prefix
    pc index namespace list -i my-index --prefix "tenant-"

    # Limit results
    pc index namespace list -i my-index --limit 10

    # JSON output
    pc index namespace list -i my-index -j
    ```
  </Accordion>
</AccordionGroup>

### Vectors

<AccordionGroup>
  <Accordion title="pc index vector delete (Delete vectors)">
    **Description**

    Deletes vectors from an index by ID, filter, or deletes all vectors in a namespace.

    **Usage**

    ```bash theme={null}
    pc index vector delete [flags]
    ```

    **Flags**

    | Long flag             | Short flag | Description                                                               |
    | :-------------------- | :--------- | :------------------------------------------------------------------------ |
    | `--index-name`        | `-i`       | Index name (required)                                                     |
    | `--namespace`         |            | Namespace to delete from (default: `__default__`)                         |
    | `--ids`               |            | Vector IDs to delete (inline JSON array, `./path.json`, or `-` for stdin) |
    | `--filter`            |            | Metadata filter (inline JSON, `./path.json`, or `-` for stdin)            |
    | `--all-vectors`       |            | Delete all vectors in the namespace                                       |
    | `--skip-confirmation` |            | Skip the confirmation prompt shown for `--all-vectors`                    |
    | `--json`              | `-j`       | Output in JSON format (also skips the confirmation prompt)                |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Delete specific vectors
    pc index vector delete -i my-index --ids '["id1"]'

    # Delete multiple vectors (inline JSON array, or JSON array in a file)
    pc index vector delete -i my-index --ids '["id1", "id2"]'

    # Delete by filter
    pc index vector delete -i my-index --filter '{"genre":"classical"}'

    # Delete all vectors in a namespace (prompts for confirmation)
    pc index vector delete -i my-index --namespace old-data --all-vectors

    # Delete all vectors without the prompt
    pc index vector delete -i my-index --namespace old-data --all-vectors --skip-confirmation
    ```

    <Note>
      Only `--all-vectors` prompts for confirmation. Targeted deletes with `--ids` or `--filter` proceed without a prompt. Pass `--skip-confirmation` (or `--json`) to bypass the `--all-vectors` prompt.
    </Note>

    <Warning>
      Vector deletion is permanent and cannot be undone.
    </Warning>
  </Accordion>

  <Accordion title="pc index vector fetch (Fetch vectors by ID or filter)">
    **Description**

    Retrieves vectors by their IDs or by a metadata filter, returning the vector values and metadata.

    **Usage**

    ```bash theme={null}
    pc index vector fetch [flags]
    ```

    **Flags**

    | Long flag            | Short flag | Description                                                              |
    | :------------------- | :--------- | :----------------------------------------------------------------------- |
    | `--index-name`       | `-i`       | Index name (required)                                                    |
    | `--namespace`        |            | Namespace to fetch from (default: `__default__`)                         |
    | `--ids`              |            | Vector IDs to fetch (inline JSON array, `./path.json`, or `-` for stdin) |
    | `--filter`           | `-f`       | Metadata filter (inline JSON, `./path.json`, or `-` for stdin)           |
    | `--limit`            | `-l`       | Maximum number of vectors to fetch                                       |
    | `--pagination-token` | `-p`       | Pagination token for next page                                           |
    | `--body`             |            | Request body JSON (inline, `./path.json`, or `-` for stdin)              |
    | `--json`             | `-j`       | Output in JSON format                                                    |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Fetch specific vectors by ID
    pc index vector fetch -i my-index --ids '["123","456","789"]'

    # Fetch from a file
    pc index vector fetch -i my-index --ids ./ids.json

    # Fetch by metadata filter
    pc index vector fetch -i my-index --filter '{"genre":{"$eq":"rock"}}'

    # Fetch from a namespace
    pc index vector fetch -i my-index --namespace tenant-a --ids '["doc-123"]'

    # JSON output
    pc index vector fetch -i my-index --ids '["vec1"]' -j
    ```

    <Note>
      Use either `--ids` or `--filter`, not both. When using `--ids`, pagination flags are not applicable.
    </Note>
  </Accordion>

  <Accordion title="pc index vector list (List vector IDs)">
    **Description**

    Lists vector IDs in a namespace with optional pagination.

    **Usage**

    ```bash theme={null}
    pc index vector list [flags]
    ```

    **Flags**

    | Long flag            | Short flag | Description                                     |
    | :------------------- | :--------- | :---------------------------------------------- |
    | `--index-name`       | `-i`       | Index name (required)                           |
    | `--namespace`        |            | Namespace to list from (default: `__default__`) |
    | `--limit`            | `-l`       | Maximum number of IDs to return                 |
    | `--pagination-token` | `-p`       | Pagination token for next page                  |
    | `--json`             | `-j`       | Output in JSON format                           |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # List vector IDs
    pc index vector list -i my-index

    # List from a namespace with limit
    pc index vector list -i my-index --namespace tenant-a --limit 50

    # JSON output
    pc index vector list -i my-index -j
    ```
  </Accordion>

  <Accordion title="pc index vector query (Query vectors)">
    **Description**

    Queries an index for similar vectors using dense vectors, sparse vectors, or vector ID.

    **Usage**

    ```bash theme={null}
    pc index vector query [flags]
    ```

    **Flags**

    | Long flag            | Short flag | Description                                                                       |
    | :------------------- | :--------- | :-------------------------------------------------------------------------------- |
    | `--index-name`       | `-i`       | Index name (required)                                                             |
    | `--namespace`        |            | Namespace to query (default: `__default__`)                                       |
    | `--id`               |            | Query by vector ID                                                                |
    | `--vector`           | `-v`       | Query vector values (inline JSON array, `./path.json`, or `-` for stdin)          |
    | `--sparse-indices`   |            | Sparse vector indices (inline JSON uint32 array, `./path.json`, or `-` for stdin) |
    | `--sparse-values`    |            | Sparse vector values (inline JSON array, `./path.json`, or `-` for stdin)         |
    | `--top-k`            | `-k`       | Number of results to return (default: 10)                                         |
    | `--filter`           | `-f`       | Metadata filter (inline JSON, `./path.json`, or `-` for stdin)                    |
    | `--include-values`   |            | Include vector values in results                                                  |
    | `--include-metadata` |            | Include metadata in results                                                       |
    | `--body`             |            | Request body JSON (inline, `./path.json`, or `-` for stdin)                       |
    | `--json`             | `-j`       | Output in JSON format                                                             |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Query by vector ID
    pc index vector query -i my-index --id "doc-123" -k 10 --include-metadata

    # Query by vector values
    pc index vector query -i my-index --vector '[0.1, 0.2, 0.3]' -k 25

    # Query with metadata filter
    pc index vector query -i my-index \
      --vector '[0.1, 0.2, 0.3]' \
      --filter '{"genre":{"$eq":"sci-fi"}}' \
      --include-metadata

    # Query from file (file contains a JSON array that specifies the query vector)
    pc index vector query -i my-index --vector ./embedding.json -k 20

    # Query with sparse vectors (inline)
    pc index vector query -i my-index \
      --sparse-indices '[0, 5, 12]' \
      --sparse-values '[0.5, 0.3, 0.8]' \
      -k 15

    # Query with sparse vectors from files
    # indices.json: [0, 5, 12]
    # values.json: [0.5, 0.3, 0.8]
    pc index vector query -i my-index \
      --sparse-indices ./indices.json \
      --sparse-values ./values.json \
      -k 15

    # Query from stdin (extract embedding from a document)
    # doc.json: {"id": "doc-123", "embedding": [0.1, 0.2, 0.3], "text": "..."}
    jq -c '.embedding' doc.json | pc index vector query -i my-index --vector - -k 10
    ```

    <Note>
      Use `--id`, `--vector`, or sparse vectors (`--sparse-indices` and `--sparse-values`) to specify what to query against. These options are mutually exclusive.
    </Note>
  </Accordion>

  <Accordion title="pc index vector update (Update vectors)">
    **Description**

    Updates a vector's values, sparse values, or metadata by ID, or updates metadata for multiple vectors matching a filter.

    **Usage**

    ```bash theme={null}
    pc index vector update [flags]
    ```

    **Flags**

    | Long flag          | Short flag | Description                                                                    |
    | :----------------- | :--------- | :----------------------------------------------------------------------------- |
    | `--index-name`     | `-i`       | Index name (required)                                                          |
    | `--namespace`      |            | Namespace containing the vector (default: `__default__`)                       |
    | `--id`             |            | Vector ID to update                                                            |
    | `--values`         |            | New vector values (inline JSON array, `./path.json`, or `-` for stdin)         |
    | `--sparse-indices` |            | New sparse indices (inline JSON uint32 array, `./path.json`, or `-` for stdin) |
    | `--sparse-values`  |            | New sparse values (inline JSON array, `./path.json`, or `-` for stdin)         |
    | `--metadata`       |            | New or updated metadata (inline JSON, `./path.json`, or `-` for stdin)         |
    | `--filter`         |            | Metadata filter for bulk update (inline JSON, `./path.json`, or `-` for stdin) |
    | `--dry-run`        |            | Preview how many records would be updated without applying changes             |
    | `--body`           |            | Request body JSON (inline, `./path.json`, or `-` for stdin)                    |
    | `--json`           | `-j`       | Output in JSON format                                                          |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Update metadata for a single vector
    pc index vector update -i my-index --id "vec1" --metadata '{"category":"updated"}'

    # Update values for a single vector
    pc index vector update -i my-index --id "vec1" --values '[0.2, 0.3, 0.4]'

    # Update sparse values
    # indices.json: [0, 5, 12]
    # values.json: [0.5, 0.3, 0.8]
    pc index vector update -i my-index --id "vec1" \
      --sparse-indices ./indices.json \
      --sparse-values ./values.json

    # Bulk update metadata by filter (preview first)
    pc index vector update -i my-index \
      --filter '{"genre":{"$eq":"sci-fi"}}' \
      --metadata '{"genre":"fantasy"}' \
      --dry-run

    # Apply the bulk update
    pc index vector update -i my-index \
      --filter '{"genre":{"$eq":"sci-fi"}}' \
      --metadata '{"genre":"fantasy"}'
    ```

    <Note>
      Use either `--id` for single vector updates or `--filter` for bulk updates. These options are mutually exclusive.
    </Note>
  </Accordion>

  <Accordion title="pc index vector upsert (Upsert vectors)">
    **Description**

    Inserts or updates vectors in an index from a JSON or JSONL file, or inline JSON. The CLI automatically batches vectors for efficient uploading. Files can contain any number of vectors—the CLI splits them into batches and sends multiple API requests as needed.

    **Usage**

    ```bash theme={null}
    pc index vector upsert [flags]
    ```

    **Flags**

    | Long flag      | Short flag | Description                                                                        |
    | :------------- | :--------- | :--------------------------------------------------------------------------------- |
    | `--index-name` | `-i`       | Index name (required)                                                              |
    | `--namespace`  |            | Namespace to upsert into (default: `__default__`)                                  |
    | `--body`       |            | Request body JSON or JSONL (inline, `./path.json[l]`, or `-` for stdin) (required) |
    | `--batch-size` | `-b`       | Size of batches to upsert (default: 500)                                           |
    | `--json`       | `-j`       | Output in JSON format                                                              |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Upsert from JSON file (with "vectors" array)
    # vectors.json: {"vectors": [{"id": "vec1", "values": [0.1, 0.2, 0.3], "metadata": {"genre": "comedy"}}]}
    pc index vector upsert -i my-index --body ./vectors.json

    # Upsert with inline JSON
    pc index vector upsert -i my-index --body '{"vectors": [{"id": "vec1", "values": [0.1, 0.2, 0.3], "metadata": {"genre": "comedy"}}]}'

    # Upsert from JSONL file (one vector per line)
    # vectors.jsonl: {"id": "vec1", "values": [0.1, 0.2, 0.3]}
    #                {"id": "vec2", "values": [0.4, 0.5, 0.6]}
    pc index vector upsert -i my-index --body ./vectors.jsonl

    # Upsert from stdin (same format as JSON or JSONL file)
    cat vectors.json | pc index vector upsert -i my-index --body -

    # Custom batch size (default: 500, max: 1000 per API request)
    pc index vector upsert -i my-index --body ./vectors.json --batch-size 1000
    ```

    <Note>
      **Batch size limits:** The API accepts up to 1000 vectors per request. The CLI defaults to batches of 500 vectors, but you can adjust this with `--batch-size` (up to 1000). Large files are automatically split into multiple batches.

      **File size:** There's no explicit file size limit—the CLI reads the entire file into memory and batches it automatically. Very large files are supported as long as they fit in available system memory.
    </Note>
  </Accordion>
</AccordionGroup>

### Records

<AccordionGroup>
  <Accordion title="pc index record search (Search records in an index)">
    **Description**

    Search an index namespace with a query text, query vector, or record ID and return the most similar records, along with their similarity scores. Optionally, rerank the initial results based on their relevance to the query.

    Searching with text is supported only for indexes with an integrated embedding configured. Searching with a query vector or record ID is supported for all indexes.

    Exactly one primary query mode must be provided:

    * `--inputs` — query text (requires an index with integrated embedding)
    * `--id` — use an existing record's vector as the query
    * `--vector` — provide a dense vector directly (all index types)
    * `--sparse-indices` + `--sparse-values` — sparse vector (all index types)

    Combine `--vector` with `--sparse-indices`/`--sparse-values` for hybrid search. Use `--body` to pass a full request object; flags take precedence over `--body` when both specify the same field.

    **Usage**

    ```bash theme={null}
    pc index record search [flags]
    ```

    **Flags**

    | Long flag          | Short flag | Description                                                                                                                                                     |
    | :----------------- | :--------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `--index-name`     | `-i`       | Name of the index to search (required)                                                                                                                          |
    | `--inputs`         |            | Query inputs for text search (inline JSON, `./path.json`, or `-` for stdin); requires integrated embedding. Mutually exclusive with `--id` and `--vector`.      |
    | `--id`             |            | Use an existing record's vector by ID for the query. Mutually exclusive with `--inputs` and `--vector`.                                                         |
    | `--vector`         | `-v`       | Dense vector values to search against (inline JSON float32 array, `./path.json`, or `-` for stdin). Mutually exclusive with `--inputs` and `--id`.              |
    | `--sparse-indices` |            | Sparse vector indices (inline JSON int32 array, `./path.json`, or `-` for stdin). Must be used together with `--sparse-values`.                                 |
    | `--sparse-values`  |            | Sparse vector values (inline JSON float32 array, `./path.json`, or `-` for stdin). Must be used together with `--sparse-indices`.                               |
    | `--top-k`          | `-k`       | Number of results to return (required)                                                                                                                          |
    | `--namespace`      |            | Namespace to search                                                                                                                                             |
    | `--filter`         |            | Metadata filter (inline JSON, `./path.json`, or `-` for stdin)                                                                                                  |
    | `--rerank`         |            | Re-score results using an inference model (inline JSON, `./path.json`, or `-` for stdin). Required fields: `model` (string), `rank_fields` (string array).      |
    | `--match-terms`    |            | Keyword terms filter for sparse integrated indexes (inline JSON, `./path.json`, or `-` for stdin). Required field: `terms` (string array). Requires `--inputs`. |
    | `--fields`         |            | Fields to return in results (inline JSON string array, `./path.json`, or `-` for stdin)                                                                         |
    | `--body`           |            | Full request body JSON (inline, `./path.json`, or `-` for stdin). Flags take precedence when both specify the same field.                                       |
    | `--json`           | `-j`       | Output in JSON format                                                                                                                                           |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Examples**

    ```bash theme={null}
    # Text search (integrated embedding indexes only)
    pc index record search --index-name my-index --inputs '{"text":"disease prevention"}' --top-k 10
    pc index record search --index-name my-index --inputs '{"text":"disease prevention"}' --namespace my-namespace --top-k 5
    pc index record search --index-name my-index --inputs '{"text":"disease prevention"}' --filter '{"category":"health"}' --top-k 10
    pc index record search --index-name my-index --inputs '{"text":"disease prevention"}' --fields '["_id","chunk_text","category"]' --top-k 10
    pc index record search --index-name my-index --inputs '{"text":"disease prevention"}' --rerank '{"model":"bge-reranker-v2-m3","rank_fields":["chunk_text"]}' --top-k 10
    pc index record search --index-name my-index --inputs '{"text":"disease prevention"}' --match-terms '{"terms":["vaccine","prevention"]}' --top-k 10

    # Search by record ID for query vector (all index types)
    pc index record search --index-name my-index --id rec-123 --top-k 10

    # Vector search (all index types)
    pc index record search --index-name my-index --vector '[0.1,0.2,0.3]' --top-k 10
    pc index record search --index-name my-index --sparse-indices '[1,5,9]' --sparse-values '[0.4,0.8,0.2]' --top-k 10
    pc index record search --index-name my-index --vector '[0.1,0.2,0.3]' --sparse-indices '[1,5,9]' --sparse-values '[0.4,0.8,0.2]' --top-k 10

    # Full request body (must include top_k in the body)
    pc index record search --index-name my-index --body ./search.json
    ```

    ```text CLI theme={null}
    Usage: 5 (read units)
    ID          SCORE       FIELDS
    rec-001     0.912340    {"category":"health","chunk_text":"vaccine research..."}
    rec-002     0.887210    {"category":"health","chunk_text":"disease prevention..."}
    ```
  </Accordion>

  <Accordion title="pc index record upsert (Upsert records into an integrated index)">
    **Description**

    Upsert records into an integrated index namespace from a JSON or JSONL payload.

    The `--body` flag accepts a JSON object containing a `"records"` array of `IntegratedRecord` objects, a raw JSON array of records, or a JSONL stream of records (one object per line). The value can be inline JSON, a path to a `.json` or `.jsonl` file, or `-` to read from stdin.

    Records are sent in batches. The default batch size is 96 (the API maximum). Use `--batch-size` to send smaller batches.

    **Usage**

    ```bash theme={null}
    pc index record upsert [flags]
    ```

    **Flags**

    | Long flag      | Short flag | Description                                                                             |
    | :------------- | :--------- | :-------------------------------------------------------------------------------------- |
    | `--index-name` | `-i`       | Name of the index to upsert into (required)                                             |
    | `--body`       |            | Request body JSON or JSONL (inline JSON, `./path.json[l]`, or `-` for stdin) (required) |
    | `--namespace`  |            | Namespace to upsert into                                                                |
    | `--batch-size` | `-b`       | Number of records per batch (default: `96`, max: `96`)                                  |
    | `--json`       | `-j`       | Output in JSON format                                                                   |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Examples**

    ```bash theme={null}
    # Upsert from a JSON file
    pc index record upsert --index-name my-index --body ./records.json

    # Upsert from a JSONL file into a specific namespace
    pc index record upsert --index-name my-index --namespace my-namespace --body ./records.jsonl

    # Upsert from stdin
    cat records.jsonl | pc index record upsert --index-name my-index --namespace my-namespace --body -
    ```
  </Accordion>
</AccordionGroup>

### Collections

<AccordionGroup>
  <Accordion title="pc index collection create (Create a collection from a pod-based index)">
    **Description**

    Creates a static copy of a pod-based index as a collection. Collections can be used to store a snapshot of an index's data for backup or migration purposes.

    **Usage**

    ```bash theme={null}
    pc index collection create [flags]
    ```

    **Flags**

    | Long flag  | Short flag | Description                                                 |
    | :--------- | :--------- | :---------------------------------------------------------- |
    | `--name`   | `-n`       | Name to give the collection (required)                      |
    | `--source` | `-s`       | Name of the pod-based index to use as the source (required) |
    | `--json`   | `-j`       | Output in JSON format                                       |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Create a collection from a pod-based index
    pc index collection create --name my-collection --source my-index
    ```

    ```text CLI theme={null}
    ATTRIBUTE     VALUE
    Name          my-collection
    State         Initializing
    Dimension     1536
    Size          0
    VectorCount   0
    Environment   us-east-1-aws
    ```
  </Accordion>

  <Accordion title="pc index collection delete (Delete a collection)">
    **Description**

    Deletes a collection permanently. This action cannot be undone.

    **Usage**

    ```bash theme={null}
    pc index collection delete [flags]
    ```

    **Flags**

    | Long flag             | Short flag | Description                                                |
    | :-------------------- | :--------- | :--------------------------------------------------------- |
    | `--name`              | `-n`       | Name of the collection to delete (required)                |
    | `--skip-confirmation` |            | Skip the deletion confirmation prompt                      |
    | `--json`              | `-j`       | Output in JSON format (also skips the confirmation prompt) |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Delete a collection (prompts for confirmation)
    pc index collection delete --name my-collection

    # Skip the confirmation prompt
    pc index collection delete --name my-collection --skip-confirmation
    ```

    <Note>
      This command prompts for confirmation before deleting. Pass `--skip-confirmation` (or `--json`) to bypass the prompt in non-interactive contexts.
    </Note>
  </Accordion>

  <Accordion title="pc index collection describe (Describe a collection by name)">
    **Description**

    Returns detailed information about a single collection, including its state, dimension, size, vector count, and environment.

    **Usage**

    ```bash theme={null}
    pc index collection describe [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description                                   |
    | :-------- | :--------- | :-------------------------------------------- |
    | `--name`  | `-n`       | Name of the collection to describe (required) |
    | `--json`  | `-j`       | Output in JSON format                         |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Describe a collection
    pc index collection describe --name my-collection
    ```

    ```text CLI theme={null}
    ATTRIBUTE     VALUE
    Name          my-collection
    State         Ready
    Dimension     1536
    Size          104857600
    VectorCount   10000
    Environment   us-east-1-aws
    ```
  </Accordion>

  <Accordion title="pc index collection list (List collections in your project)">
    **Description**

    Lists all collections in your current project, sorted alphabetically by name.

    **Usage**

    ```bash theme={null}
    pc index collection list [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description           |
    | :-------- | :--------- | :-------------------- |
    | `--json`  | `-j`       | Output in JSON format |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # List all collections
    pc index collection list
    ```

    ```text CLI theme={null}
    NAME             DIMENSION   SIZE        STATUS   VECTORS   ENVIRONMENT
    my-collection    1536        104857600   Ready    10000     us-east-1-aws
    ```
  </Accordion>
</AccordionGroup>

### Backups

<AccordionGroup>
  <Accordion title="pc index backup create (Create a backup)">
    **Description**

    Creates a backup of a serverless index. Backups are static copies that only consume storage.

    **Usage**

    ```bash theme={null}
    pc index backup create [flags]
    ```

    **Flags**

    | Long flag       | Short flag | Description                                                          |
    | :-------------- | :--------- | :------------------------------------------------------------------- |
    | `--index-name`  | `-i`       | Name of the index to back up (required)                              |
    | `--name`        |            | Human-readable label for the backup (the backup ID is always a UUID) |
    | `--description` | `-d`       | Description for the backup                                           |
    | `--json`        | `-j`       | Output in JSON format                                                |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Create a backup
    pc index backup create -i my-index

    # Create with name and description
    pc index backup create -i my-index --name "nightly-backup" -d "Nightly backup before deployment"

    # JSON output
    pc index backup create -i my-index -j
    ```
  </Accordion>

  <Accordion title="pc index backup delete (Delete a backup)">
    **Description**

    Permanently deletes a backup. This operation cannot be undone.

    **Usage**

    ```bash theme={null}
    pc index backup delete [flags]
    ```

    **Flags**

    | Long flag             | Short flag | Description                                                |
    | :-------------------- | :--------- | :--------------------------------------------------------- |
    | `--id`                | `-i`       | Backup ID to delete (required)                             |
    | `--skip-confirmation` |            | Skip the deletion confirmation prompt                      |
    | `--json`              | `-j`       | Output in JSON format (also skips the confirmation prompt) |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Delete a backup by ID (prompts for confirmation)
    pc index backup delete -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f

    # Skip the confirmation prompt
    pc index backup delete -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f --skip-confirmation
    ```

    <Note>
      This command prompts for confirmation before deleting. Pass `--skip-confirmation` (or `--json`) to bypass the prompt in non-interactive contexts.
    </Note>

    <Warning>
      Backup deletion is permanent and cannot be undone.
    </Warning>
  </Accordion>

  <Accordion title="pc index backup describe (Show backup details)">
    **Description**

    Displays detailed information about a specific backup.

    **Usage**

    ```bash theme={null}
    pc index backup describe [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description                      |
    | :-------- | :--------- | :------------------------------- |
    | `--id`    | `-i`       | Backup ID to describe (required) |
    | `--json`  | `-j`       | Output in JSON format            |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Describe a backup
    pc index backup describe -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f

    # JSON output
    pc index backup describe -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f -j
    ```
  </Accordion>

  <Accordion title="pc index backup list (List backups)">
    **Description**

    Lists backups in the current project, optionally filtered by index name.

    **Usage**

    ```bash theme={null}
    pc index backup list [flags]
    ```

    **Flags**

    | Long flag            | Short flag | Description                    |
    | :------------------- | :--------- | :----------------------------- |
    | `--index-name`       | `-i`       | Filter backups by index name   |
    | `--limit`            | `-l`       | Maximum number of results      |
    | `--pagination-token` | `-p`       | Pagination token for next page |
    | `--json`             | `-j`       | Output in JSON format          |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # List all backups in the project
    pc index backup list

    # List backups for a specific index
    pc index backup list --index-name my-index

    # Limit results
    pc index backup list --limit 10

    # JSON output
    pc index backup list -j
    ```
  </Accordion>

  <Accordion title="pc index restore (Restore an index from a backup)">
    **Description**

    Creates a new index from a backup.

    **Usage**

    ```bash theme={null}
    pc index restore [flags]
    ```

    **Flags**

    | Long flag               | Short flag | Description                                          |
    | :---------------------- | :--------- | :--------------------------------------------------- |
    | `--id`                  | `-i`       | Backup ID (UUID) to restore from (required)          |
    | `--name`                | `-n`       | Name for the new index (required)                    |
    | `--deletion-protection` |            | Enable deletion protection - `enabled` or `disabled` |
    | `--tags`                | `-t`       | Tags to apply to the new index (key=value pairs)     |
    | `--json`                | `-j`       | Output in JSON format                                |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Restore an index from a backup
    pc index restore -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f -n restored-index

    # Restore with tags and deletion protection
    pc index restore -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f -n restored-index \
      --tags env=prod,team=search \
      --deletion-protection enabled

    # JSON output
    pc index restore -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f -n restored-index -j
    ```
  </Accordion>

  <Accordion title="pc index restore describe (Show restore job details)">
    **Description**

    Displays the status and details of a restore job.

    **Usage**

    ```bash theme={null}
    pc index restore describe [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description                           |
    | :-------- | :--------- | :------------------------------------ |
    | `--id`    | `-i`       | Restore job ID to describe (required) |
    | `--json`  | `-j`       | Output in JSON format                 |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Describe a restore job
    pc index restore describe -i rj-abc123

    # JSON output
    pc index restore describe -i rj-abc123 -j
    ```
  </Accordion>

  <Accordion title="pc index restore list (List restore jobs)">
    **Description**

    Lists all restore jobs in the current project.

    **Usage**

    ```bash theme={null}
    pc index restore list [flags]
    ```

    **Flags**

    | Long flag            | Short flag | Description                    |
    | :------------------- | :--------- | :----------------------------- |
    | `--limit`            | `-l`       | Maximum number of results      |
    | `--pagination-token` | `-p`       | Pagination token for next page |
    | `--json`             | `-j`       | Output in JSON format          |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # List restore jobs
    pc index restore list

    # Limit results
    pc index restore list --limit 10

    # JSON output
    pc index restore list -j
    ```
  </Accordion>
</AccordionGroup>

### Imports

<AccordionGroup>
  <Accordion title="pc index import start (Start an import from a storage URI)">
    **Description**

    Start an import that loads vector data from a storage provider into a serverless index. The URI must begin with the scheme of a supported provider (for example, `s3://`).

    For private buckets, configure a storage integration in the Pinecone console and pass the integration ID with `--integration-id`.

    Use `--error-mode` to control behavior when records fail: `continue` skips failing records and keeps going; `abort` stops the import on first error. Defaults to `continue`.

    **Usage**

    ```bash theme={null}
    pc index import start [flags]
    ```

    **Flags**

    | Long flag          | Short flag | Description                                                           |
    | :----------------- | :--------- | :-------------------------------------------------------------------- |
    | `--index-name`     | `-i`       | Name of the index to import into (required)                           |
    | `--uri`            | `-u`       | URI of the data to import, for example `s3://bucket/path/` (required) |
    | `--integration-id` |            | Storage integration ID for private buckets                            |
    | `--error-mode`     |            | How to handle record errors: `continue` (default) or `abort`          |
    | `--json`           | `-j`       | Output in JSON format                                                 |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Examples**

    ```bash theme={null}
    # Start an import from a public S3 bucket
    pc index import start --index-name my-index --uri s3://my-bucket/data/

    # Start an import from a private bucket using a storage integration
    pc index import start --index-name my-index --uri s3://my-bucket/data/ --integration-id intg-123

    # Abort on the first error instead of continuing
    pc index import start --index-name my-index --uri s3://my-bucket/data/ --error-mode abort

    # JSON output
    pc index import start --index-name my-index --uri s3://my-bucket/data/ -j
    ```

    ```text CLI theme={null}
    Import imp-abc123 started.
    ATTRIBUTE    VALUE
    Import ID    imp-abc123
    ```
  </Accordion>

  <Accordion title="pc index import describe (Describe an import operation)">
    **Description**

    Show the current status and details of an import operation, including
    percent complete, records imported, and any error messages.

    **Usage**

    ```bash theme={null}
    pc index import describe [flags]
    ```

    **Flags**

    | Long flag      | Short flag | Description                                        |
    | :------------- | :--------- | :------------------------------------------------- |
    | `--index-name` | `-i`       | Name of the index the import belongs to (required) |
    | `--id`         |            | ID of the import to describe (required)            |
    | `--json`       | `-j`       | Output in JSON format                              |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Describe an import operation
    pc index import describe --index-name my-index --id import-123

    # JSON output
    pc index import describe --index-name my-index --id import-123 -j
    ```

    ```text CLI theme={null}
    ATTRIBUTE         VALUE
    Import ID         import-123
    Status            InProgress
    URI               s3://my-bucket/data/
    Percent Complete  45.0%
    Records Imported  450
    Created At        2024-01-15 12:00:00
    Finished At       -
    Error             None
    ```
  </Accordion>

  <Accordion title="pc index import list (List import operations for an index)">
    **Description**

    List bulk import operations for the given index, with optional pagination.

    **Usage**

    ```bash theme={null}
    pc index import list [flags]
    ```

    **Flags**

    | Long flag            | Short flag | Description                                               |
    | :------------------- | :--------- | :-------------------------------------------------------- |
    | `--index-name`       | `-i`       | Name of the index to list imports for (required)          |
    | `--limit`            | `-l`       | Maximum number of imports to return                       |
    | `--pagination-token` | `-p`       | Pagination token to continue a previous listing operation |
    | `--json`             | `-j`       | Output in JSON format                                     |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Examples**

    ```bash theme={null}
    # List all imports for an index
    pc index import list --index-name my-index

    # List imports with a page size limit
    pc index import list --index-name my-index --limit 10

    # Continue paginating from a previous call
    pc index import list --index-name my-index --pagination-token eyJ...

    # JSON output
    pc index import list --index-name my-index -j
    ```

    ```text CLI theme={null}
    IMPORT ID     STATUS      URI                     PERCENT  RECORDS  CREATED              FINISHED
    imp-abc123    Completed   s3://my-bucket/data/    100.0%   1000     2024-01-15 12:00:00  2024-01-15 12:05:00
    imp-def456    InProgress  s3://other-bucket/data/ 45.0%    450      2024-01-15 13:00:00  -
    ```
  </Accordion>

  <Accordion title="pc index import cancel (Cancel an in-progress import operation)">
    **Description**

    Cancel an import operation that is currently pending or in progress.
    Already-completed or failed imports cannot be canceled.

    **Usage**

    ```bash theme={null}
    pc index import cancel [flags]
    ```

    **Flags**

    | Long flag      | Short flag | Description                                        |
    | :------------- | :--------- | :------------------------------------------------- |
    | `--index-name` | `-i`       | Name of the index the import belongs to (required) |
    | `--id`         |            | ID of the import to cancel (required)              |
    | `--json`       | `-j`       | Output in JSON format                              |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Cancel an import operation
    pc index import cancel --index-name my-index --id import-123

    # JSON output
    pc index import cancel --index-name my-index --id import-123 -j
    ```

    ```text CLI theme={null}
    Import import-123 canceled.
    ```
  </Accordion>
</AccordionGroup>

### Projects

<AccordionGroup>
  <Accordion title="pc project create (Create a new project)">
    **Description**

    Creates a new project in your [target organization](/reference/cli/target-context), using the specified configuration.

    **Usage**

    ```bash theme={null}
    pc project create [flags]
    ```

    **Flags**

    | Long flag            | Short flag | Description                                                    |
    | :------------------- | :--------- | :------------------------------------------------------------- |
    | `--force-encryption` |            | Enable encryption with CMEK                                    |
    | `--json`             | `-j`       | Output in JSON format                                          |
    | `--name`             | `-n`       | Project name (required)                                        |
    | `--target`           |            | Automatically target the project in the CLI after it's created |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Basic project creation
    pc project create -n "demo-project"
    ```
  </Accordion>

  <Accordion title="pc project delete (Delete a project)">
    **Description**

    Permanently deletes a project and all its resources. This operation cannot be undone.

    **Usage**

    ```bash theme={null}
    pc project delete [flags]
    ```

    **Flags**

    | Long flag             | Short flag | Description                                                 |
    | :-------------------- | :--------- | :---------------------------------------------------------- |
    | `--id`                | `-i`       | Project ID (optional, uses target project if not specified) |
    | `--json`              | `-j`       | Output in JSON format                                       |
    | `--skip-confirmation` |            | Skip confirmation prompt                                    |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Delete target project
    pc project delete

    # Delete specific project
    pc project delete -i proj-abc123

    # Skip confirmation
    pc project delete -i proj-abc123 --skip-confirmation
    ```

    <Note>
      Must delete all indexes and collections in the project first. If the deleted project is your current target, set a new target after deleting it.
    </Note>
  </Accordion>

  <Accordion title="pc project describe (Show project details)">
    **Description**

    Displays detailed information about a specific project, including various details.

    **Usage**

    ```bash theme={null}
    pc project describe [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description           |
    | :-------- | :--------- | :-------------------- |
    | `--id`    | `-i`       | Project ID (required) |
    | `--json`  | `-j`       | Output in JSON format |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Describe a project
    pc project describe -i proj-abc123

    # JSON output
    pc project describe -i proj-abc123 --json

    # Find ID and describe
    pc project list
    pc project describe -i proj-abc123
    ```
  </Accordion>

  <Accordion title="pc project list (List all projects)">
    **Description**

    Displays all projects in your [target organization](/reference/cli/target-context), including various details.

    **Usage**

    ```bash theme={null}
    pc project list [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description           |
    | :-------- | :--------- | :-------------------- |
    | `--json`  | `-j`       | Output in JSON format |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # List all projects
    pc project list

    # JSON output
    pc project list --json

    # List after login
    pc auth login
    pc auth target -o "my-org"
    pc project list
    ```
  </Accordion>

  <Accordion title="pc project update (Update project settings)">
    **Description**

    Modifies the configuration of the [target project](/reference/cli/target-context), or a specific project ID.

    **Usage**

    ```bash theme={null}
    pc project update [flags]
    ```

    **Flags**

    | Long flag            | Short flag | Description                         |
    | :------------------- | :--------- | :---------------------------------- |
    | `--force-encryption` | `-f`       | Enable/disable encryption with CMEK |
    | `--id`               | `-i`       | Project ID (required)               |
    | `--json`             | `-j`       | Output in JSON format               |
    | `--name`             | `-n`       | New project name                    |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Update name
    pc project update -i proj-abc123 -n "new-name"
    ```
  </Accordion>
</AccordionGroup>

### Organizations

<AccordionGroup>
  <Accordion title="pc organization delete (Delete an organization)">
    **Description**

    Permanently deletes an organization and all its resources. This operation cannot be undone.

    **Usage**

    ```bash theme={null}
    pc organization delete [flags]
    ```

    **Flags**

    | Long flag             | Short flag | Description                |
    | :-------------------- | :--------- | :------------------------- |
    | `--id`                | `-i`       | Organization ID (required) |
    | `--json`              | `-j`       | Output in JSON format      |
    | `--skip-confirmation` |            | Skip confirmation prompt   |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Delete an organization
    pc organization delete -i org-abc123

    # Skip confirmation
    pc organization delete -i org-abc123 --skip-confirmation
    ```

    <Note>
      This is a highly destructive action. Deletion is permanent. If the deleted organization is your current [target](/reference/cli/target-context), set a new target after deleting.
    </Note>
  </Accordion>

  <Accordion title="pc organization describe (Show organization details)">
    **Description**

    Displays detailed information about a specific organization, including name, ID, creation date, payment status, plan, and support tier.

    **Usage**

    ```bash theme={null}
    pc organization describe [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description                |
    | :-------- | :--------- | :------------------------- |
    | `--id`    | `-i`       | Organization ID (required) |
    | `--json`  | `-j`       | Output in JSON format      |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Describe an organization
    pc organization describe -i org-abc123

    # JSON output
    pc organization describe -i org-abc123 --json

    # Find ID and describe
    pc organization list
    pc organization describe -i org-abc123
    ```
  </Accordion>

  <Accordion title="pc organization list (List organizations)">
    **Description**

    Displays all organizations that the authenticated user has access to, including name, ID, creation date, payment status, plan, and support tier.

    **Usage**

    ```bash theme={null}
    pc organization list [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description           |
    | :-------- | :--------- | :-------------------- |
    | `--json`  | `-j`       | Output in JSON format |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # List all organizations
    pc organization list

    # JSON output
    pc organization list --json

    # List after login
    pc auth login
    pc organization list
    ```
  </Accordion>

  <Accordion title="pc organization update (Update organization settings)">
    **Description**

    Modifies the configuration of the [target organization](/reference/cli/target-context), or a specific organization ID.

    **Usage**

    ```bash theme={null}
    pc organization update [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description                |
    | :-------- | :--------- | :------------------------- |
    | `--id`    | `-i`       | Organization ID (required) |
    | `--json`  | `-j`       | Output in JSON format      |
    | `--name`  | `-n`       | New organization name      |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Update name
    pc organization update -i org-abc123 -n "new-name"

    # Verify changes
    pc organization update -i org-abc123 -n "Acme Corp"
    pc organization describe -i org-abc123
    ```
  </Accordion>
</AccordionGroup>

### API keys

<AccordionGroup>
  <Accordion title="pc api-key create (Create a new API key)">
    **Description**

    Creates a new API key for the current [target project](/reference/cli/target-context) or a specific project ID. Optionally stores the key locally for CLI use.

    **Usage**

    ```bash theme={null}
    pc api-key create [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description                                                                             |
    | :-------- | :--------- | :-------------------------------------------------------------------------------------- |
    | `--id`    | `-i`       | Project ID (optional, uses target project if not specified)                             |
    | `--json`  | `-j`       | Output in JSON format                                                                   |
    | `--name`  | `-n`       | Key name (required)                                                                     |
    | `--roles` |            | Roles to assign (default: `ProjectEditor`)                                              |
    | `--store` |            | Store the key locally for CLI use (automatically replaces any existing CLI-managed key) |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Basic key creation
    pc api-key create -n "my-key"

    # Create and store locally
    pc api-key create -n "my-key" --store

    # Create with specific role
    pc api-key create -n "my-key" --store --roles ProjectEditor

    # Create for specific project
    pc api-key create -n "my-key" -i proj-abc123
    ```

    <Note>
      API keys are scoped to a specific organization and project.
    </Note>
  </Accordion>

  <Accordion title="pc api-key delete (Delete an API key)">
    **Description**

    Permanently deletes an API key. Applications using this key immediately lose access.

    **Usage**

    ```bash theme={null}
    pc api-key delete [flags]
    ```

    **Flags**

    | Long flag             | Short flag | Description              |
    | :-------------------- | :--------- | :----------------------- |
    | `--id`                | `-i`       | API key ID (required)    |
    | `--skip-confirmation` |            | Skip confirmation prompt |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Delete an API key
    pc api-key delete -i key-abc123

    # Skip confirmation
    pc api-key delete -i key-abc123 --skip-confirmation

    # Delete and clean up local storage
    pc api-key delete -i key-abc123
    pc auth local-keys prune --skip-confirmation
    ```

    <Note>
      Deletion is permanent. Applications using this key immediately lose access to Pinecone.
    </Note>
  </Accordion>

  <Accordion title="pc api-key describe (Show API key details)">
    **Description**

    Displays detailed information about a specific API key, including its name, ID, project ID, and roles.

    **Usage**

    ```bash theme={null}
    pc api-key describe [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description           |
    | :-------- | :--------- | :-------------------- |
    | `--id`    | `-i`       | API key ID (required) |
    | `--json`  | `-j`       | Output in JSON format |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Describe an API key
    pc api-key describe -i key-abc123

    # JSON output
    pc api-key describe -i key-abc123 --json

    # Find ID and describe
    pc api-key list
    pc api-key describe -i key-abc123
    ```

    <Note>
      Does not display the actual key value.
    </Note>
  </Accordion>

  <Accordion title="pc api-key list (List all API keys)">
    **Description**

    Displays a list of all of the [target project's](/reference/cli/target-context) API keys, as found in  Pinecone (regardless of whether they are stored locally by the CLI). Displays various details about each key, including name, ID, project ID, and roles.

    **Usage**

    ```bash theme={null}
    pc api-key list [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description                                                 |
    | :-------- | :--------- | :---------------------------------------------------------- |
    | `--id`    | `-i`       | Project ID (optional, uses target project if not specified) |
    | `--json`  | `-j`       | Output in JSON format                                       |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # List keys for target project
    pc api-key list

    # List for specific project
    pc api-key list -i proj-abc123

    # JSON output
    pc api-key list --json
    ```

    <Note>
      Does not display key values.
    </Note>
  </Accordion>

  <Accordion title="pc api-key update (Update API key settings)">
    **Description**

    Updates the name and roles of an API key.

    **Usage**

    ```bash theme={null}
    pc api-key update [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description           |
    | :-------- | :--------- | :-------------------- |
    | `--id`    | `-i`       | API key ID (required) |
    | `--json`  | `-j`       | Output in JSON format |
    | `--name`  | `-n`       | New key name          |
    | `--roles` | `-r`       | Roles to assign       |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Update name
    pc api-key update -i key-abc123 -n "new-name"

    # Update roles
    pc api-key update -i key-abc123 -r ProjectEditor

    # Verify changes
    pc api-key update -i key-abc123 -n "production-key"
    pc api-key describe -i key-abc123
    ```

    <Note>
      Cannot change the actual key. If you need a different key, create a new one.
    </Note>
  </Accordion>
</AccordionGroup>

### Config

<AccordionGroup>
  <Accordion title="pc config list (List all configuration settings and their current values)">
    **Description**

    Lists all CLI configuration settings and their current values. Sensitive values like `api-key` are masked by default; use `--reveal` to see the full value. Hidden settings such as `environment` are included when `--all` is passed.

    **Usage**

    ```bash theme={null}
    pc config list [flags]
    ```

    **Flags**

    | Long flag  | Short flag | Description                                               |
    | :--------- | :--------- | :-------------------------------------------------------- |
    | `--reveal` |            | Reveal the full value for sensitive settings like api-key |
    | `--json`   | `-j`       | Output in JSON format                                     |
    | `--all`    |            | Include hidden settings such as environment               |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    pc config list
    pc config list --all
    pc config list --reveal
    pc config list --json
    ```

    ```text CLI theme={null}
    KEY         VALUE             ENV VAR NAME        ENV VAR OVERRIDE  DESCRIPTION
    api-key     ****abcd****      PINECONE_API_KEY     false             Default API key for authenticating with Pinecone
    color       true                                                     Enable colored output
    ```
  </Accordion>

  <Accordion title="pc config get <key> (Get the current value of a configuration setting)">
    **Description**

    Gets the current value of a configuration setting. Valid keys are: `api-key`, `color`, `environment`. Sensitive values like `api-key` are masked by default; use `--reveal` to see the full value.

    **Usage**

    ```bash theme={null}
    pc config get <key> [flags]
    ```

    **Flags**

    | Long flag  | Short flag | Description                                               |
    | :--------- | :--------- | :-------------------------------------------------------- |
    | `--reveal` |            | Reveal the full value for sensitive settings like api-key |
    | `--json`   | `-j`       | Output in JSON format                                     |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    pc config get api-key
    pc config get api-key --reveal
    pc config get environment
    pc config get color
    ```
  </Accordion>

  <Accordion title="pc config describe <key> (Show detailed information about a configuration setting)">
    **Description**

    Displays detailed information about a specific CLI configuration setting, including its current value, whether an environment variable is overriding it, and valid values. Valid keys are: `api-key`, `color`, `environment`.

    **Usage**

    ```bash theme={null}
    pc config describe <key> [flags]
    ```

    **Flags**

    | Long flag  | Short flag | Description                                               |
    | :--------- | :--------- | :-------------------------------------------------------- |
    | `--reveal` |            | Reveal the full value for sensitive settings like api-key |
    | `--json`   | `-j`       | Output in JSON format                                     |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    pc config describe api-key
    pc config describe color
    pc config describe color --json
    ```

    ```text CLI theme={null}
    KEY               api-key
    VALUE             ****abcd****
    ENV VAR NAME      $PINECONE_API_KEY
    ENV VAR OVERRIDE  false
    SENSITIVE         true
    DESCRIPTION       Default API key for authenticating with Pinecone
    ```
  </Accordion>

  <Accordion title="pc config set <key> <value> (Set a configuration value)">
    **Description**

    Sets a CLI configuration value. Valid keys are: `api-key`, `color`, `environment`. The value is persisted to the local config file.

    **Usage**

    ```bash theme={null}
    pc config set <key> <value> [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description           |
    | :-------- | :--------- | :-------------------- |
    | `--json`  | `-j`       | Output in JSON format |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    pc config set api-key pcsk_...
    pc config set environment staging
    pc config set color false
    ```
  </Accordion>

  <Accordion title="pc config unset <key> (Reset a configuration value to its default)">
    **Description**

    Resets a CLI configuration value to its default. Valid keys are: `api-key`, `color`, `environment`.

    **Usage**

    ```bash theme={null}
    pc config unset <key> [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description           |
    | :-------- | :--------- | :-------------------- |
    | `--json`  | `-j`       | Output in JSON format |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    pc config unset api-key
    pc config unset color
    ```
  </Accordion>
</AccordionGroup>


# CLI quickstart
Source: https://docs.pinecone.io/reference/cli/quickstart

Pinecone CLI quickstart for installing pc, authenticating, and managing indexes, vectors, and data imports directly from your terminal.

The Pinecone CLI (`pc`) lets you manage Pinecone resources directly from your terminal.

## Install

<Tabs>
  <Tab title="macOS (Homebrew)">
    ```bash theme={null}
    brew tap pinecone-io/tap
    brew install pinecone-io/tap/pinecone
    ```
  </Tab>

  <Tab title="Other platforms">
    Pre-built binaries for macOS, Linux, and Windows are available on the [GitHub Releases page](https://github.com/pinecone-io/cli/releases).

    | Platform | Architectures                          |
    | :------- | :------------------------------------- |
    | macOS    | Intel (x86\_64), Apple Silicon (ARM64) |
    | Linux    | x86\_64, ARM64, i386                   |
    | Windows  | x86\_64, i386                          |
  </Tab>
</Tabs>

## Authenticate

```bash theme={null}
pc auth login
```

Visit the URL in your terminal to sign in. The CLI automatically sets your default organization and project.

To target a different org/project:

```bash theme={null}
pc target -o "my-org" -p "my-project"
```

<Tip>
  For CI/CD or automation, you can also authenticate with a [service account](/reference/cli/authentication#service-account) or [API key](/reference/cli/authentication#api-key).
</Tip>

## Manage indexes

```bash theme={null}
# List indexes
pc index list

# Create an index
pc index create -n my-index -d 3 -m cosine -c aws -r us-east-1

# Get index details
pc index describe -i my-index

# Get index statistics
pc index stats -i my-index
```

## Work with vectors

```bash theme={null}
# Upsert vectors (from file or inline JSON)
pc index vector upsert -i my-index \
  --body '{"vectors": [{"id": "vec1", "values": [0.1, 0.2, 0.3], "metadata": {"genre": "comedy"}}]}'

# Import from a large dataset in object storage (S3, GCS, Azure)
pc index import start -i my-index --uri s3://my-bucket/data/

# Check the progress of an import operation
pc index import list --i my-index
pc index import describe --i my-index --id import-123

# Query (vector can be inline or in a file)
pc index vector query -i my-index \
  --vector '[0.1, 0.2, 0.3]' \
  --top-k 10 \
  --include-metadata

# Fetch by ID (from file or inline JSON)
pc index vector fetch -i my-index --ids '["vec1","vec2"]'

# List vector IDs from an index
pc index vector list -i my-index
```

## Manage namespaces

```bash theme={null}
# List namespaces
pc index namespace list -i my-index

# Create a namespace
pc index namespace create -i my-index --name tenant-a

# Delete a namespace
pc index namespace delete -i my-index --name tenant-a
```

## Back up and restore

```bash theme={null}
# Create a backup
pc index backup create -i my-index --name "my-index-backup"

# List backups (show index, backup name, backup ID, etc.)
pc index backup list -i my-index

# Restore from backup (by ID, not name)
pc index restore -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f -n restored-index
```

## JSON output

Add `-j` to any command for JSON output:

```bash theme={null}
pc index list -j
pc index describe -i my-index -j
```

## Getting help

Use `-h` or `--help` with any command to see available options:

```bash theme={null}
pc -h
pc index -h
pc index create -h
```

## Next steps

* [Command reference](/reference/cli/command-reference) — Full list of commands and flags
* [Authentication](/reference/cli/authentication) — Service accounts, API keys, and auth priority
* [Target context](/reference/cli/target-context) — How org/project targeting works


# CLI target context
Source: https://docs.pinecone.io/reference/cli/target-context

Pinecone CLI: The CLI's **target context** determines which organization and project your commands operate on. You must authenticate before setting target.

The CLI's **target context** determines which organization and project your commands operate on. You must [authenticate](/reference/cli/authentication) before setting target context.

## Flags

| Flag                | Short | Default | Description                                                                       |
| ------------------- | ----- | ------- | --------------------------------------------------------------------------------- |
| `--org`             | `-o`  | —       | Target organization by name. Mutually exclusive with `--organization-id`.         |
| `--organization-id` | —     | —       | Target organization by ID. Mutually exclusive with `--org`.                       |
| `--project`         | `-p`  | —       | Target project by name. Mutually exclusive with `--project-id`.                   |
| `--project-id`      | —     | —       | Target project by ID. Mutually exclusive with `--project`.                        |
| `--show`            | `-s`  | `false` | Show the current target context.                                                  |
| `--clear`           | —     | `false` | Clear the stored target context.                                                  |
| `--json`            | `-j`  | `false` | Output as JSON. In non-TTY environments (CI/CD, pipes), JSON output is automatic. |

<Note>
  `--org` and `--organization-id` are mutually exclusive — use one or the other. The same applies to `--project` and `--project-id`.
</Note>

## How operations use target context

| Operation type                   | Scope                                    |
| -------------------------------- | ---------------------------------------- |
| Control plane (indexes, backups) | Target project                           |
| Data plane (vectors, namespaces) | Target project + specified index         |
| Admin API (organizations)        | No target context needed                 |
| Admin API (projects)             | Target organization                      |
| Admin API (API keys)             | Target project (unless `--id` specified) |

## Target context by auth method

### User login

After `pc auth login`, the CLI auto-targets your default organization and its first project.

```bash theme={null}
# Change target
pc target -o "my-org" -p "my-project"
```

### Service account

**Via CLI command:** After `pc auth configure --client-id --client-secret`, the CLI auto-targets the service account's organization. For the project:

* If one project exists, it's auto-targeted
* If multiple exist, you're prompted (or use `--project-id`)
* If none exist, create one and target it manually

**Via environment variables:** If using `PINECONE_CLIENT_ID` and `PINECONE_CLIENT_SECRET` without running `pc auth configure`, no target context is set automatically. Run `pc target` to set it.

```bash theme={null}
# Change project (org is fixed to the service account's org)
pc target -p "my-project"

# Or select interactively
pc target
```

### API key

<Warning>
  When using an API key, control plane and data plane operations use the **key's org/project scope**, not the CLI's stored target context. The `pc target --show` output does not reflect what these operations actually use.
</Warning>

API keys are scoped to a specific org and project and cannot access resources outside that scope.

Admin API operations still use your user login or service account credentials (API keys can't authenticate Admin API calls).

## Managing target context

```bash theme={null}
pc target --show   # View current target
pc target --clear  # Clear target context
```

### JSON mode and non-TTY environments

Running `pc target --json` with no targeting flags returns the current target context as a JSON object. This is a local-state read — **no authentication is required**:

```bash theme={null}
pc target --json
```

In non-TTY environments (CI/CD pipelines, shell pipes, scripts), JSON output is automatic — the same as passing `--json` explicitly. You do not need to add the flag in automation contexts.

Use `--organization-id` and `--project-id` (instead of name flags) to set context reliably in scripts, since IDs are stable and unaffected by renames:

```bash theme={null}
pc target --organization-id "org-abc123" --project-id "proj-xyz789" --json
```


# Pinecone SDKs overview
Source: https://docs.pinecone.io/reference/pinecone-sdks

Browse official Pinecone SDKs for Python, Node.js, Java, and Go, including the version mappings between SDK releases and API versions.

## Pinecone SDKs

Official Pinecone SDKs provide convenient access to the [Pinecone APIs](/reference/api/introduction).

<CardGroup>
  <Card title="Python SDK" icon="python" href="/reference/sdks/python/overview" />

  <Card title="Node.js SDK" icon="node-js" href="/reference/sdks/node/overview" />

  <Card title="Java SDK" icon="java" href="/reference/sdks/java/overview" />

  <Card title="Go SDK" icon="golang" href="/reference/sdks/go/overview" />
</CardGroup>

## SDK versions

SDK versions are pinned to specific [API versions](/reference/api/versioning). When a new API version is released, a new version of the SDK is also released.

The mappings between API versions and SDK versions are as follows:

|                                               | `2026-04`   | `2025-10` | `2025-04` | `2025-01` | `2024-10` | `2024-07`     | `2024-04` |
| --------------------------------------------- | :---------- | :-------- | :-------- | :-------- | :-------- | :------------ | :-------- |
| [Python SDK](/reference/sdks/python/overview) | v9.x        | v8.x      | v7.x      | v6.x      | v5.3.x    | v5.0.x-v5.2.x | v4.x      |
| [Node.js SDK](/reference/sdks/node/overview)  | v8.x        | v7.x      | v6.x      | v5.x      | v4.x      | v3.x          | v2.x      |
| [Java SDK](/reference/sdks/java/overview)     | Coming soon | v6.x      | v5.x      | v4.x      | v3.x      | v2.x          | v1.x      |
| [Go SDK](/reference/sdks/go/overview)         | v6.x        | v5.x      | v4.x      | v3.x      | v2.x      | v1.x          | v0.x      |

When a new stable API version is released, you should upgrade your SDK to the latest version to ensure compatibility with the latest API changes.

<Note>
  The Java SDK targeting API version `2026-04` will be available soon.
</Note>

## Limitations

While Pinecone tracks read unit usage with decimal precision, the Pinecone API and SDKs round these values up to the nearest whole number in query, fetch, and list responses. For example, if a query uses 0.45 read units, the API and SDKs will report it as 1 read unit.

For precise read unit reporting, see [index-level metrics](/guides/production/monitoring) or the organization-wide [Usage dashboard](/guides/manage-cost/monitor-usage-and-costs#monitor-organization-level-usage-and-costs).

## Community SDKs

Find community-contributed SDKs for Pinecone. These libraries are not supported by Pinecone.

* [Ruby SDK](https://github.com/ScotterC/pinecone) (contributed by [ScotterC](https://github.com/ScotterC))

* [Scala SDK](https://github.com/cequence-io/pinecone-scala) (contributed by [cequence-io](https://github.com/cequence-io))

* [PHP SDK](https://github.com/probots-io/pinecone-php) (contributed by [protobots-io](https://github.com/probots-io))


# Pinecone Go SDK
Source: https://docs.pinecone.io/reference/sdks/go/overview

Install and use the Pinecone Go SDK to manage indexes and namespaces, upsert vectors, run semantic search, and call the Admin and Inference APIs from Go.

<Tip>
  For installation instructions and usage examples, see the [Go SDK documentation](https://github.com/pinecone-io/go-pinecone). To report an issue or request a feature, [file an issue on GitHub](https://github.com/pinecone-io/go-pinecone/issues).
</Tip>

## Requirements

The Pinecone Go SDK requires a Go version with [modules](https://go.dev/wiki/Modules) support.

## SDK versions

SDK versions are pinned to specific [API versions](/reference/api/versioning). When a new API version is released, a new version of the SDK is also released.

The mappings between API versions and Go SDK versions are as follows:

| API version | SDK version |
| :---------- | :---------- |
| `2026-04`   | v6.x        |
| `2025-10`   | v5.x        |
| `2025-04`   | v4.x        |
| `2025-01`   | v3.x        |
| `2024-10`   | v2.x        |
| `2024-07`   | v1.x        |
| `2024-04`   | v0.x        |

When a new stable API version is released, you should upgrade your SDK to the latest version to ensure compatibility with the latest API changes.

## Install

To install the latest version of the [Go SDK](https://github.com/pinecone-io/go-pinecone), add a dependency to the current module:

```shell theme={null}
go get github.com/pinecone-io/go-pinecone/v6/pinecone
```

To install a specific version of the Go SDK, run the following command:

```shell theme={null}
go get github.com/pinecone-io/go-pinecone/v6/pinecone@<version>
```

To check your SDK version, run the following command:

```shell theme={null}
go list -u -m all | grep go-pinecone
```

## Upgrade

<Warning>
  Before upgrading to `v3.0.0` or later, update all relevant code to account for the breaking changes explained [here](/release-notes/2025#2025-02-07-4).
</Warning>

Each major version carries its version number in the module path, so crossing a major requires updating the import path in every file that uses the SDK. For example, moving from `v4` to `v6` means changing:

```go theme={null}
// before
import "github.com/pinecone-io/go-pinecone/v4/pinecone"

// after
import "github.com/pinecone-io/go-pinecone/v6/pinecone"
```

Apart from the module path, `v5.0.0` and `v6.0.0` are backward compatible with the release lines before them.

If you already have the Go SDK, upgrade to the latest version as follows:

```shell theme={null}
go get -u github.com/pinecone-io/go-pinecone/v6/pinecone@latest
```

## Initialize

Once installed, you can import the SDK and then use an [API key](/guides/production/security-overview#api-keys) to initialize a client instance:

```Go theme={null}
package main

import (
    "context"
    "log"

    "github.com/pinecone-io/go-pinecone/v6/pinecone"
)

func main() {
    ctx := context.Background()

    pc, err := pinecone.NewClient(pinecone.NewClientParams{
        ApiKey: "YOUR_API_KEY",
    })
    if err != nil {
        log.Fatalf("Failed to create Client: %v", err)
    }
} 
```

To manage organizations, projects, API keys, and [role-based access control](/guides/production/manage-rbac), initialize an `AdminClient` with [service account](/guides/organizations/manage-service-accounts) credentials instead:

```Go theme={null}
package main

import (
    "context"
    "log"
    "os"

    "github.com/pinecone-io/go-pinecone/v6/pinecone"
)

func main() {
    ctx := context.Background()

    adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
        ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
        ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
    })
    if err != nil {
        log.Fatalf("Failed to create AdminClient: %v", err)
    }
}
```


# Reference
Source: https://docs.pinecone.io/reference/sdks/go/reference

Reference documentation for the Pinecone Go SDK, including client setup, types, and methods for managing indexes and vector data operations.



# OpenTelemetry support
Source: https://docs.pinecone.io/reference/sdks/java/open-telemetry

Monitor Pinecone Java SDK operations with OpenTelemetry metrics for client latency, server processing time, and errors via Prometheus.

The Pinecone Java SDK provides built-in support for capturing per-operation response metadata, making it straightforward to monitor your Pinecone usage with [OpenTelemetry](https://opentelemetry.io/) or any other observability system.

With this feature, you can track client-side latency, server processing time, network overhead, error rates, and more for every data plane operation your application makes.

## How it all fits together

The SDK's observability support is designed to be flexible. You don't need to adopt the entire observability stack at once -- start simple and add layers as your needs grow.

Here are the components involved and how they relate to each other:

* **Pinecone Java SDK**: Exposes a `ResponseMetadataListener` callback, a plain Java interface with no external dependencies. At its simplest, you can log the metadata to the console. No additional tools required.
* **[OpenTelemetry](https://opentelemetry.io/) (OTel)**: An open standard and SDK for producing structured telemetry data (metrics, traces, logs). If you want standardized metrics that follow [semantic conventions](https://opentelemetry.io/docs/specs/semconv/database/database-spans/), you add the OTel SDK and wire it to the listener. This is optional.
* **OTel Collector**: A vendor-neutral service that receives telemetry from your app and forwards it to a storage backend. Optional -- many setups export directly from the app to a backend.
* **Prometheus**: A time-series database that stores metrics, making them queryable over time. One popular storage option.
* **Grafana**: A visualization and dashboarding tool that queries Prometheus (or other backends) and displays charts and alerts. One popular visualization option.

A common setup chains these together:

```
Your App (OTel SDK) → OTel Collector → Prometheus (storage) → Grafana (visualization)
```

<Note>
  This is just one example pipeline. You can substitute Datadog, New Relic, or any OTel-compatible backend. You can also skip OTel entirely and use [Micrometer](#example-micrometerprometheus), custom logging, or any approach that suits your stack.
</Note>

## Response metadata listener

The Java SDK captures response metadata through a `ResponseMetadataListener` -- a functional interface you provide when building the Pinecone client. The listener is called after each data plane operation completes (whether it succeeds or fails), and receives a `ResponseMetadata` object containing timing, status, and context information.

The SDK itself has no OpenTelemetry dependency. You bring your own observability library and decide what to do with the metadata.

### Supported operations

The following data plane operations are instrumented, for both synchronous (`Index`) and asynchronous (`AsyncIndex`) usage:

| Operation | Description                |
| --------- | -------------------------- |
| `upsert`  | Insert or update vectors   |
| `query`   | Search for similar vectors |
| `fetch`   | Retrieve vectors by ID     |
| `update`  | Update vector metadata     |
| `delete`  | Delete vectors             |

### Available metadata

Each `ResponseMetadata` object provides the following fields:

| Method                   | Description                                        | OTel attribute            |
| ------------------------ | -------------------------------------------------- | ------------------------- |
| `getOperationName()`     | Operation type (e.g., `upsert`, `query`)           | `db.operation.name`       |
| `getIndexName()`         | Pinecone index name                                | `pinecone.index_name`     |
| `getNamespace()`         | Namespace (empty string if default)                | `db.namespace`            |
| `getServerAddress()`     | Pinecone server host                               | `server.address`          |
| `getClientDurationMs()`  | Total round-trip time in ms (always available)     | --                        |
| `getServerDurationMs()`  | Server processing time in ms (may be `null`)       | --                        |
| `getNetworkOverheadMs()` | Client minus server duration in ms (may be `null`) | --                        |
| `getStatus()`            | `"success"` or `"error"`                           | `status`                  |
| `getGrpcStatusCode()`    | Raw gRPC status code (e.g., `OK`, `UNAVAILABLE`)   | `db.response.status_code` |
| `getErrorType()`         | Error category, or `null` if successful            | `error.type`              |

Possible `errorType` values: `validation`, `connection`, `server`, `rate_limit`, `timeout`, `auth`, `not_found`, `unknown`.

### Recommended metrics

If you're recording OTel metrics, the SDK example project uses these metric names, which follow [OTel semantic conventions for database clients](https://opentelemetry.io/docs/specs/semconv/database/database-spans/):

| Metric                                | Type      | Unit | Description                     |
| ------------------------------------- | --------- | ---- | ------------------------------- |
| `db.client.operation.duration`        | Histogram | ms   | Client-measured round-trip time |
| `pinecone.server.processing.duration` | Histogram | ms   | Server processing time          |
| `db.client.operation.count`           | Counter   | --   | Total number of operations      |

## Quick start: Simple logging

The simplest way to use the listener is to log the metadata directly. This requires no additional dependencies beyond the Pinecone SDK:

```java theme={null}
import io.pinecone.clients.Pinecone;

Pinecone client = new Pinecone.Builder("PINECONE_API_KEY")
    .withResponseMetadataListener(metadata -> {
        System.out.printf("Operation: %s | Client: %dms | Server: %sms | Network: %sms | Status: %s%n",
            metadata.getOperationName(),
            metadata.getClientDurationMs(),
            metadata.getServerDurationMs(),
            metadata.getNetworkOverheadMs(),
            metadata.getStatus());
    })
    .build();
```

Once configured, every data plane operation automatically triggers the listener:

```java theme={null}
Index index = client.getIndexConnection("my-index");
index.upsert("id-1", Arrays.asList(0.1f, 0.2f, 0.3f));
// Output: Operation: upsert | Client: 47ms | Server: 40ms | Network: 7ms | Status: success
```

## Quick start: OpenTelemetry integration

To record structured metrics with OpenTelemetry, add the OTel SDK dependencies and wire a metrics recorder to the listener.

### 1. Add dependencies

Add the following to your `pom.xml`:

```xml theme={null}
<dependencies>
    <!-- Pinecone SDK -->
    <dependency>
        <groupId>io.pinecone</groupId>
        <artifactId>pinecone-client</artifactId>
        <version>LATEST</version>
    </dependency>

    <!-- OpenTelemetry SDK -->
    <dependency>
        <groupId>io.opentelemetry</groupId>
        <artifactId>opentelemetry-sdk</artifactId>
    </dependency>
    <dependency>
        <groupId>io.opentelemetry</groupId>
        <artifactId>opentelemetry-sdk-metrics</artifactId>
    </dependency>

    <!-- OTLP exporter (sends metrics to an OTel Collector or compatible backend) -->
    <dependency>
        <groupId>io.opentelemetry</groupId>
        <artifactId>opentelemetry-exporter-otlp</artifactId>
    </dependency>
</dependencies>

<!-- Use the OTel BOM to manage versions -->
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.opentelemetry</groupId>
            <artifactId>opentelemetry-bom</artifactId>
            <version>1.35.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
```

### 2. Create a metrics recorder

The SDK's [example project](https://github.com/pinecone-io/pinecone-java-client/tree/main/examples/java-otel-metrics) includes a reusable `PineconeMetricsRecorder` class you can copy into your project. It implements `ResponseMetadataListener` and records all three recommended metrics with proper OTel attributes:

```java theme={null}
import io.opentelemetry.api.common.AttributeKey;
import io.opentelemetry.api.common.Attributes;
import io.opentelemetry.api.common.AttributesBuilder;
import io.opentelemetry.api.metrics.LongCounter;
import io.opentelemetry.api.metrics.LongHistogram;
import io.opentelemetry.api.metrics.Meter;
import io.pinecone.configs.ResponseMetadata;
import io.pinecone.configs.ResponseMetadataListener;

public class PineconeMetricsRecorder implements ResponseMetadataListener {

    private static final AttributeKey<String> DB_SYSTEM = AttributeKey.stringKey("db.system");
    private static final AttributeKey<String> DB_OPERATION_NAME = AttributeKey.stringKey("db.operation.name");
    private static final AttributeKey<String> DB_NAMESPACE = AttributeKey.stringKey("db.namespace");
    private static final AttributeKey<String> PINECONE_INDEX_NAME = AttributeKey.stringKey("pinecone.index_name");
    private static final AttributeKey<String> SERVER_ADDRESS = AttributeKey.stringKey("server.address");
    private static final AttributeKey<String> STATUS = AttributeKey.stringKey("status");
    private static final AttributeKey<String> ERROR_TYPE = AttributeKey.stringKey("error.type");

    private final LongHistogram clientDurationHistogram;
    private final LongHistogram serverDurationHistogram;
    private final LongCounter operationCounter;

    public PineconeMetricsRecorder(Meter meter) {
        this.clientDurationHistogram = meter.histogramBuilder("db.client.operation.duration")
                .setDescription("Duration of Pinecone operations from client perspective")
                .setUnit("ms")
                .ofLongs()
                .build();

        this.serverDurationHistogram = meter.histogramBuilder("pinecone.server.processing.duration")
                .setDescription("Server processing time from x-pinecone-response-duration-ms header")
                .setUnit("ms")
                .ofLongs()
                .build();

        this.operationCounter = meter.counterBuilder("db.client.operation.count")
                .setDescription("Total number of Pinecone operations")
                .setUnit("{operation}")
                .build();
    }

    @Override
    public void onResponse(ResponseMetadata metadata) {
        AttributesBuilder attributesBuilder = Attributes.builder()
                .put(DB_SYSTEM, "pinecone")
                .put(DB_OPERATION_NAME, metadata.getOperationName())
                .put(PINECONE_INDEX_NAME, metadata.getIndexName())
                .put(SERVER_ADDRESS, metadata.getServerAddress())
                .put(STATUS, metadata.getStatus());

        String namespace = metadata.getNamespace();
        if (namespace != null && !namespace.isEmpty()) {
            attributesBuilder.put(DB_NAMESPACE, namespace);
        }

        if (!metadata.isSuccess() && metadata.getErrorType() != null) {
            attributesBuilder.put(ERROR_TYPE, metadata.getErrorType());
        }

        Attributes attributes = attributesBuilder.build();

        clientDurationHistogram.record(metadata.getClientDurationMs(), attributes);

        Long serverDuration = metadata.getServerDurationMs();
        if (serverDuration != null) {
            serverDurationHistogram.record(serverDuration, attributes);
        }

        operationCounter.add(1, attributes);
    }
}
```

### 3. Wire it into the Pinecone client

Initialize the OTel SDK, create the recorder, and pass it to the Pinecone client builder:

```java theme={null}
import io.opentelemetry.api.metrics.Meter;
import io.opentelemetry.sdk.OpenTelemetrySdk;
import io.opentelemetry.sdk.metrics.SdkMeterProvider;
import io.opentelemetry.sdk.metrics.export.PeriodicMetricReader;
import io.opentelemetry.exporter.otlp.metrics.OtlpGrpcMetricExporter;
import io.pinecone.clients.Pinecone;

// Set up OTel with OTLP exporter
OtlpGrpcMetricExporter exporter = OtlpGrpcMetricExporter.builder()
    .setEndpoint("http://localhost:4317")
    .build();

SdkMeterProvider meterProvider = SdkMeterProvider.builder()
    .registerMetricReader(PeriodicMetricReader.builder(exporter).build())
    .build();

OpenTelemetrySdk openTelemetry = OpenTelemetrySdk.builder()
    .setMeterProvider(meterProvider)
    .build();

// Create the metrics recorder
Meter meter = openTelemetry.getMeter("pinecone.client");
PineconeMetricsRecorder recorder = new PineconeMetricsRecorder(meter);

// Build the Pinecone client with the recorder
Pinecone client = new Pinecone.Builder("PINECONE_API_KEY")
    .withResponseMetadataListener(recorder)
    .build();

// Use the client normally -- metrics are recorded automatically
Index index = client.getIndexConnection("my-index");
index.upsert("id-1", Arrays.asList(0.1f, 0.2f, 0.3f));
index.query(3, Arrays.asList(0.1f, 0.2f, 0.3f));
```

<Tip>
  For a complete runnable example with Docker Compose, Prometheus, and Grafana, see the [java-otel-metrics example project](https://github.com/pinecone-io/pinecone-java-client/tree/main/examples/java-otel-metrics) in the SDK repository.
</Tip>

## Example: Micrometer/Prometheus

If your application uses [Micrometer](https://micrometer.io/) (common in Spring Boot), you can wire the listener to Micrometer instead of the OTel SDK:

```java theme={null}
import io.micrometer.core.instrument.MeterRegistry;
import io.micrometer.core.instrument.Timer;
import io.pinecone.clients.Pinecone;
import java.util.concurrent.TimeUnit;

Pinecone client = new Pinecone.Builder("PINECONE_API_KEY")
    .withResponseMetadataListener(metadata -> {
        Timer.builder("pinecone.client.duration")
            .tag("operation", metadata.getOperationName())
            .tag("index", metadata.getIndexName())
            .tag("status", metadata.getStatus())
            .register(meterRegistry)
            .record(metadata.getClientDurationMs(), TimeUnit.MILLISECONDS);
    })
    .build();
```

## Visualizing metrics

Once your metrics are flowing to a backend, you can build dashboards to monitor your Pinecone operations. If you're using Prometheus and Grafana, here are some useful queries:

**P50 and P95 client latency:**

```promql theme={null}
histogram_quantile(0.5, sum(rate(db_client_operation_duration_milliseconds_bucket[5m])) by (le))
histogram_quantile(0.95, sum(rate(db_client_operation_duration_milliseconds_bucket[5m])) by (le))
```

**P95 latency by operation type:**

```promql theme={null}
histogram_quantile(0.95, sum(rate(db_client_operation_duration_milliseconds_bucket[5m])) by (le, db_operation_name))
```

**Operation count by type:**

```promql theme={null}
sum by (db_operation_name) (db_client_operation_count_total)
```

## Understanding the latency breakdown

The `ResponseMetadata` object provides three timing values that help you pinpoint the source of latency issues:

| Component        | Method                   | What it measures                                                                                                                             |
| ---------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| Client duration  | `getClientDurationMs()`  | Total round-trip time from request start to response completion. Always available.                                                           |
| Server duration  | `getServerDurationMs()`  | Time the Pinecone backend spent processing the request. Extracted from the `x-pinecone-response-duration-ms` response header. May be `null`. |
| Network overhead | `getNetworkOverheadMs()` | The difference: client duration minus server duration. Includes network latency, serialization, and deserialization. May be `null`.          |

Use these values to diagnose performance issues:

* **High server duration**: The bottleneck is on the Pinecone backend. Consider optimizing your query (e.g., reducing `topK`, using metadata filters), or check the [Pinecone status page](https://status.pinecone.io/).
* **High network overhead**: The bottleneck is in the network path between your application and Pinecone. Consider deploying your application closer to your index's cloud region, or check for network issues.

## Limitations

* **Data plane operations only.** Control plane operations (e.g., creating or deleting indexes) are not currently instrumented.
* **Bulk import operations** are not yet instrumented.
* **Server duration may be unavailable.** The `getServerDurationMs()` method returns `null` if the `x-pinecone-response-duration-ms` header is not present in the response.
* **Synchronous callback.** The listener is called synchronously after the gRPC response is received. Keep implementations lightweight and non-blocking to avoid adding latency to your operations. For heavy processing, queue the metadata for async handling.
* **Exceptions are swallowed.** Exceptions thrown by the listener are logged but do not affect the operation result.

## Best practices

* **Keep listeners lightweight.** Record metrics or enqueue work -- don't do I/O or heavy computation in the callback.
* **Follow OTel semantic conventions.** Use the attribute names shown in the [recommended metrics](#recommended-metrics) table for interoperability with standard dashboards and tooling.
* **Monitor both client and server duration.** Tracking both lets you separate Pinecone backend performance from network conditions.
* **Set alerts on error rates.** Use the `status` and `error.type` attributes to build alerts for elevated error rates across operations.


# Pinecone Java SDK
Source: https://docs.pinecone.io/reference/sdks/java/overview

Install and use the Pinecone Java SDK to manage indexes and namespaces, upsert vectors, run semantic search, and call the Admin and Inference APIs from Java.

<Tip>
  For installation instructions and usage examples, see the [Pinecone Java SDK documentation](https://github.com/pinecone-io/pinecone-java-client). To report an issue or request a feature, [file an issue on GitHub](https://github.com/pinecone-io/pinecone-java-client/issues).
</Tip>

## Requirements

The Pinecone Java SDK requires Java 1.8 or later.

## SDK versions

SDK versions are pinned to specific [API versions](/reference/api/versioning). When a new API version is released, a new version of the SDK is also released.

The mappings between API versions and Java SDK versions are as follows:

| API version | SDK version |
| :---------- | :---------- |
| `2025-04`   | v5.x        |
| `2025-01`   | v4.x        |
| `2024-10`   | v3.x        |
| `2024-07`   | v2.x        |
| `2024-04`   | v1.x        |

When a new stable API version is released, you should upgrade your SDK to the latest version to ensure compatibility with the latest API changes.

## Install

To install the latest version of the [Java SDK](https://github.com/pinecone-io/pinecone-java-client), add a dependency to the current module:

```shell Java theme={null}
# Maven
<dependency>
  <groupId>io.pinecone</groupId>
  <artifactId>pinecone-client</artifactId>
  <version>5.0.0</version>
</dependency>

# Gradle
implementation "io.pinecone:pinecone-client:5.0.0"
```

Alternatively, you can download the standalone uberjar [pinecone-client-4.0.0-all.jar](https://repo1.maven.org/maven2/io/pinecone/pinecone-client/4.0.0/pinecone-client-4.0.0-all.jar), which bundles the Pinecone SDK and all dependencies together. You can include this in your classpath like you do with any third-party JAR without having to obtain the `pinecone-client` dependencies separately.

## Upgrade

<Warning>
  Before upgrading to `v4.0.0`, update all relevant code to account for the breaking changes explained [here](/release-notes/2025#2025-02-07-3).
</Warning>

If you are already using the Java SDK, upgrade the dependency in the current module to the latest version:

```shell Java theme={null}
# Maven
<dependency>
  <groupId>io.pinecone</groupId>
  <artifactId>pinecone-client</artifactId>
  <version>5.0.0</version>
</dependency>

# Gradle
implementation "io.pinecone:pinecone-client:5.0.0"
```

## Initialize

Once installed, you can import the SDK and then use an [API key](/guides/production/security-overview#api-keys) to initialize a client instance:

```Java theme={null}
import io.pinecone.clients.Pinecone;
import org.openapitools.db_control.client.model.*;

public class InitializeClientExample {
    public static void main(String[] args) {
        Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build();
    }
}
```

## Observability

The Java SDK supports capturing per-operation response metadata for all data plane operations, including client-side latency, server processing time, network overhead, and error details. You can use this metadata with [OpenTelemetry](https://opentelemetry.io/), Micrometer, or any other observability system to monitor your Pinecone usage in production.

For setup instructions and examples, see [OpenTelemetry support](/reference/sdks/java/open-telemetry).


# Reference
Source: https://docs.pinecone.io/reference/sdks/java/reference

Reference documentation for the Pinecone Java SDK, including client setup, types, and methods for managing indexes and vector data operations.



# Pinecone Node.js SDK
Source: https://docs.pinecone.io/reference/sdks/node/overview

Install and use the Pinecone Node.js and TypeScript SDK to manage indexes, upsert vectors, run semantic search, and call the Admin and Inference APIs.

<Tip>
  For installation instructions, usage examples, and reference information, see the [Pinecone Node.js SDK documentation](https://sdk.pinecone.io/typescript/). To report an issue or request a feature, [file an issue on GitHub](https://github.com/pinecone-io/pinecone-ts-client/issues).
</Tip>

## Requirements

The Pinecone Node SDK requires TypeScript 4.1 or later and Node 18.x or later.

## SDK versions

SDK versions are pinned to specific [API versions](/reference/api/versioning). When a new API version is released, a new version of the SDK is also released.

The mappings between API versions and Node.js SDK versions are as follows:

| API version | SDK version |
| :---------- | :---------- |
| `2026-04`   | v8.x        |
| `2025-10`   | v7.x        |
| `2025-04`   | v6.x        |
| `2025-01`   | v5.x        |
| `2024-10`   | v4.x        |
| `2024-07`   | v3.x        |
| `2024-04`   | v2.x        |

When a new stable API version is released, you should upgrade your SDK to the latest version to ensure compatibility with the latest API changes.

## Install

To install the latest version of the [Node.js SDK](https://github.com/pinecone-io/pinecone-ts-client), written in TypeScript, run the following command:

```Shell theme={null}
npm install @pinecone-database/pinecone
```

To check your SDK version, run the following command:

```Shell theme={null}
npm list | grep @pinecone-database/pinecone
```

## Upgrade

If you already have the Node.js SDK, upgrade to the latest version as follows:

```Shell theme={null}
npm install @pinecone-database/pinecone@latest
```

## Initialize

Once installed, you can import the library and then use an [API key](/guides/projects/manage-api-keys) to initialize a client instance:

```JavaScript theme={null}
import { Pinecone } from '@pinecone-database/pinecone';

const pc = new Pinecone({
    apiKey: 'YOUR_API_KEY'
});
```

To manage organizations, projects, API keys, and [role-based access control](/guides/production/manage-rbac), initialize an `AdminClient` with [service account](/guides/organizations/manage-service-accounts) credentials instead. This requires v8.2.0 or later:

```JavaScript theme={null}
import { AdminClient } from '@pinecone-database/pinecone';

// Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
const admin = new AdminClient();
```

You can also pass `clientId` and `clientSecret` directly to the constructor instead of setting environment variables.

## Proxy configuration

If your network setup requires you to interact with Pinecone through a proxy, you can pass a custom `ProxyAgent` from the [`undici` library](https://undici.nodejs.org/#/). Below is an example of how to construct an `undici` `ProxyAgent` that routes network traffic through a [`mitm` proxy server](https://mitmproxy.org/) while hitting Pinecone's `/indexes` endpoint.

<Note>
  The following strategy relies on Node's native [`fetch`](https://nodejs.org/docs/latest/api/globals.html#fetch) implementation, released in Node v16 and stabilized in Node v21. If you are running Node versions 18-21, you may experience issues stemming from the instability of the feature. There are currently no known issues related to proxying in Node v18+.
</Note>

```JavaScript JavaScript theme={null}
import {
  Pinecone,
  type PineconeConfiguration,
} from '@pinecone-database/pinecone';
import { Dispatcher, ProxyAgent } from 'undici';
import * as fs from 'fs';

const cert = fs.readFileSync('path/to/mitmproxy-ca-cert.pem');

const client = new ProxyAgent({
  uri: 'https://your-proxy.com',
  requestTls: {
    port: 'YOUR_PROXY_SERVER_PORT',
    ca: cert,
    host: 'YOUR_PROXY_SERVER_HOST',
  },
});

const customFetch = (
  input: string | URL | Request,
  init: RequestInit | undefined
) => {
  return fetch(input, {
    ...init,
    dispatcher: client as Dispatcher,
    keepalive: true,  # optional
  });
};

const config: PineconeConfiguration = {
  apiKey:
    'YOUR_API_KEY',
  fetchApi: customFetch,
};

const pc = new Pinecone(config);

const indexes = async () => {
  return await pc.listIndexes();
};

indexes().then((response) => {
  console.log('My indexes: ', response);
});
```


# Reference
Source: https://docs.pinecone.io/reference/sdks/node/reference

Reference documentation for the Pinecone Node.js SDK, including client setup, types, and methods for managing indexes and vector data operations.



# Pinecone Python SDK
Source: https://docs.pinecone.io/reference/sdks/python/overview

Install and use the Pinecone SDK for Pinecone Python SDK: auth, typed clients, and API operations. For installation instructions, usage examples, and.

<Tip>
  For installation instructions, usage examples, and reference information, see the [Pinecone Python SDK documentation](https://sdk.pinecone.io/python/). To report an issue or request a feature, [file an issue on GitHub](https://github.com/pinecone-io/pinecone-python-client/issues).
</Tip>

The Pinecone Python SDK is distributed on PyPI using the package name `pinecone`. By default, the `pinecone` package has a minimal set of dependencies and interacts with Pinecone via HTTP requests. However, you can install the following extras to unlock additional functionality:

* `pinecone[grpc]` adds dependencies on `grpcio` and related libraries needed to run data operations such as upserts and queries over [gRPC](https://grpc.io/) for a modest performance improvement.

* `pinecone[asyncio]` adds a dependency on `aiohttp` and enables usage of `async` methods for use with [asyncio](https://docs.python.org/3/library/asyncio.html). For more details, see [Async requests](#async-requests).

## Requirements

The Pinecone Python SDK requires Python 3.9 or later. It has been tested with CPython versions from 3.9 to 3.13.

## SDK versions

SDK versions are pinned to specific [API versions](/reference/api/versioning). When a new API version is released, a new version of the SDK is also released.

The mappings between API versions and Python SDK versions are as follows:

| API version | SDK version   |
| :---------- | :------------ |
| `2025-04`   | v7.x          |
| `2025-01`   | v6.x          |
| `2024-10`   | v5.3.x        |
| `2024-07`   | v5.0.x-v5.2.x |
| `2024-04`   | v4.x          |

When a new stable API version is released, you should upgrade your SDK to the latest version to ensure compatibility with the latest API changes.

## Install

To install the latest version of the [Python SDK](https://github.com/pinecone-io/pinecone-python-client), run the following command:

```shell theme={null}
# Install the latest version
pip install pinecone

# Install the latest version with gRPC extras
pip install "pinecone[grpc]"

# Install the latest version with asyncio extras
pip install "pinecone[asyncio]"
```

To install a specific version of the Python SDK, run the following command:

```shell pip theme={null}
# Install a specific version
pip install pinecone==<version>

# Install a specific version with gRPC extras
pip install "pinecone[grpc]"==<version>

# Install a specific version with asyncio extras
pip install "pinecone[asyncio]"==<version>
```

To check your SDK version, run the following command:

```shell pip theme={null}
pip show pinecone
```

<Note>
  To use the [Inference API](/reference/api/introduction#inference), you must be on version 5.0.0 or later.
</Note>

### Install the Pinecone Assistant Python plugin

As of Python SDK v7.0.0, the `pinecone-plugin-assistant` package is included by default. It is only necessary to install the package if you are using a version of the Python SDK prior to v7.0.0.

```shell HTTP theme={null}
pip install --upgrade pinecone pinecone-plugin-assistant
```

## Upgrade

<Warning>
  Before upgrading to `v6.0.0`, update all relevant code to account for the breaking changes explained [here](https://github.com/pinecone-io/pinecone-python-client/blob/main/docs/upgrading.md).

  Also, make sure to upgrade using the `pinecone` package name instead of `pinecone-client`; upgrading with the latter will not work as of `v6.0.0`.
</Warning>

If you already have the Python SDK, upgrade to the latest version as follows:

```shell theme={null}
# Upgrade to the latest version
pip install pinecone --upgrade

# Upgrade to the latest version with gRPC extras
pip install "pinecone[grpc]" --upgrade

# Upgrade to the latest version with asyncio extras
pip install "pinecone[asyncio]" --upgrade
```

## Initialize

Once installed, you can import the library and then use an [API key](/guides/projects/manage-api-keys) to initialize a client instance:

<CodeGroup>
  ```Python HTTP theme={null}
  from pinecone import Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")
  ```

  ```python gRPC theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")
  ```
</CodeGroup>

When [creating an index](/guides/index-data/create-an-index), import the `ServerlessSpec` or `PodSpec` class as well:

<CodeGroup>
  ```Python Serverless index theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone
  from pinecone import ServerlessSpec

  pc = Pinecone(api_key="YOUR_API_KEY")

  pc.create_index(
    name="docs-example",
    dimension=1536,
    metric="cosine",
    spec=ServerlessSpec(
      cloud="aws",
      region="us-east-1"
    )
  )
  ```

  ```Python Pod-based index theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone
  from pinecone import PodSpec

  pc = Pinecone(api_key="YOUR_API_KEY")

  pc.create_index(
    name="docs-example",
    dimension=1536,
    metric="cosine",
    spec=PodSpec(
      environment="us-west-1-gcp",
      pod_type="p1.x1",
      pods=1
    )
  )
  ```
</CodeGroup>

## Proxy configuration

If your network setup requires you to interact with Pinecone through a proxy, you will need to pass additional configuration using optional keyword parameters:

* `proxy_url`: The location of your proxy. This could be an HTTP or HTTPS URL depending on your proxy setup.
* `proxy_headers`: Accepts a python dictionary which can be used to pass any custom headers required by your proxy. If your proxy is protected by authentication, use this parameter to pass basic authentication headers with a digest of your username and password. The `make_headers` utility from `urllib3` can be used to help construct the dictionary. **Note:** Not supported with Asyncio.
* `ssl_ca_certs`: By default, the client will perform SSL certificate verification using the CA bundle maintained by Mozilla in the [`certifi`](https://pypi.org/project/certifi/) package. If your proxy is using self-signed certicates, use this parameter to specify the path to the certificate (PEM format).
* `ssl_verify`: SSL verification is enabled by default, but it is disabled when set to `False`. It is not recommened to go into production with SSL verification disabled.

<CodeGroup>
  ```python HTTP theme={null}
  from pinecone import Pinecone
  import urllib3
  from urllib3.util import make_headers

  pc = Pinecone(
      api_key="YOUR_API_KEY",
      proxy_url='https://your-proxy.com',
      proxy_headers=make_headers(proxy_basic_auth='username:password'),
      ssl_ca_certs='path/to/cert-bundle.pem'
  )
  ```

  ```python gRPC theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone
  import urllib3
  from urllib3.util import make_headers

  pc = Pinecone(
      api_key="YOUR_API_KEY",
      proxy_url='https://your-proxy.com',
      proxy_headers=make_headers(proxy_basic_auth='username:password'),
      ssl_ca_certs='path/to/cert-bundle.pem'
  )
  ```

  ```python asyncio theme={null}
  import asyncio
  from pinecone import PineconeAsyncio
  	
  async def main():
      async with PineconeAsyncio(
          api_key="YOUR_API_KEY",
          proxy_url='https://your-proxy.com',
          ssl_ca_certs='path/to/cert-bundle.pem'
      ) as pc:
          # Do async things
          await pc.list_indexes()

  asyncio.run(main())
  ```
</CodeGroup>

## Async requests

Pinecone Python SDK versions 6.0.0 and later provide `async` methods for use with [asyncio](https://docs.python.org/3/library/asyncio.html). Asyncio support makes it possible to use Pinecone with modern async web frameworks such as [FastAPI](https://fastapi.tiangolo.com/), [Quart](https://quart.palletsprojects.com/en/latest/), and [Sanic](https://sanic.dev/en/), and should significantly increase the efficiency of running requests in parallel.

Use the [`PineconeAsyncio`](https://sdk.pinecone.io/python/asyncio.html) class to create and manage indexes and the [`IndexAsyncio`](https://sdk.pinecone.io/python/asyncio.html#pinecone.db_data.IndexAsyncio) class to read and write index data. To ensure that sessions are properly closed, use the `async with` syntax when creating `PineconeAsyncio` and `IndexAsyncio` objects.

<CodeGroup>
  ```python Manage indexes theme={null}
  # pip install "pinecone[asyncio]"
  import asyncio
  from pinecone import PineconeAsyncio, ServerlessSpec

  async def main():
      async with PineconeAsyncio(api_key="YOUR_API_KEY") as pc:
          if not await pc.has_index(index_name):
              desc = await pc.create_index(
                  name="docs-example",
                  dimension=1536,
                  metric="cosine",
                  spec=ServerlessSpec(
                      cloud="aws",
                      region="us-east-1"
                  ),
                  deletion_protection="disabled",
                  tags={
                      "environment": "development"
                  }
              )

  asyncio.run(main())
  ```

  ```python Read and write index data theme={null}
  # pip install "pinecone[asyncio]"
  import asyncio
  from pinecone import Pinecone

  async def main():
      pc = Pinecone(api_key="YOUR_API_KEY")
      async with pc.IndexAsyncio(host="INDEX_HOST") as idx:
          await idx.upsert_records(
              namespace="example-namespace",
              records=[
                  {
                      "id": "1",
                      "title": "The Great Gatsby",
                      "author": "F. Scott Fitzgerald",
                      "description": "The story of the mysteriously wealthy Jay Gatsby and his love for the beautiful Daisy Buchanan.",
                      "year": 1925,
                  },
                  {
                      "id": "2",
                      "title": "To Kill a Mockingbird",
                      "author": "Harper Lee",
                      "description": "A young girl comes of age in the segregated American South and witnesses her father's courageous defense of an innocent black man.",
                      "year": 1960,
                  },
                  {
                      "id": "3",
                      "title": "1984",
                      "author": "George Orwell",
                      "description": "In a dystopian future, a totalitarian regime exercises absolute control through pervasive surveillance and propaganda.",
                      "year": 1949,
                  },
              ]
          )

  asyncio.run(main())
  ```
</CodeGroup>

## Query across namespaces

Each query is limited to a single [namespace](/guides/index-data/indexing-overview#namespaces). However, the Pinecone Python SDK provides a `query_namespaces` utility method to run a query in parallel across multiple namespaces in an index and then merge the result sets into a single ranked result set with the `top_k` most relevant results.

The `query_namespaces` method accepts most of the same arguments as `query` with the addition of a required `namespaces` parameter.

<Tabs>
  <Tab title="Python SDK without gRPC">
    When using the Python SDK without gRPC extras, to get good performance, it is important to set values for the `pool_threads` and `connection_pool_maxsize` properties on the index client. The `pool_threads` setting is the number of threads available to execute requests, while `connection_pool_maxsize` is the number of cached http connections that will be held. Since these tasks are not computationally heavy and are mainly i/o bound, it should be okay to have a high ratio of threads to cpus.

    The combined results include the sum of all read unit usage used to perform the underlying queries for each namespace.

    ```python Python theme={null}
    from pinecone import Pinecone

    pc = Pinecone(api_key="YOUR_API_KEY")
    index = pc.Index(
        name="docs-example",
        pool_threads=50,             # <-- make sure to set these
        connection_pool_maxsize=50,  # <-- make sure to set these
    )

    query_vec = [ 0.1, ...] # an embedding vector with same dimension as the index
    combined_results = index.query_namespaces(
        vector=query_vec,
        namespaces=['ns1', 'ns2', 'ns3', 'ns4'],
        metric="cosine",
        top_k=10,
        include_values=False,
        include_metadata=True,
        filter={"genre": { "$eq": "comedy" }},
        show_progress=False,
    )

    for scored_vec in combined_results.matches:
        print(scored_vec)
    print(combined_results.usage)
    ```
  </Tab>

  <Tab title="Python SDK with gRPC">
    When using the Python SDK with gRPC extras, there is no need to set the `connection_pool_maxsize` because grpc makes efficient use of open connections by default.

    ```python Python theme={null}
    from pinecone.grpc import PineconeGRPC

    pc = PineconeGRPC(api_key="YOUR_API_KEY")
    index = pc.Index(
        name="docs-example",
        pool_threads=50, # <-- make sure to set this
    )

    query_vec = [ 0.1, ...] # an embedding vector with same dimension as the index
    combined_results = index.query_namespaces(
        vector=query_vec,
        namespaces=['ns1', 'ns2', 'ns3', 'ns4'],
        metric="cosine",
        top_k=10,
        include_values=False,
        include_metadata=True,
        filter={"genre": { "$eq": "comedy" }},
        show_progress=False,
    )

    for scored_vec in combined_results.matches:
        print(scored_vec)
    print(combined_results.usage)
    ```
  </Tab>
</Tabs>

## Upsert from a dataframe

To quickly ingest data when using the [Python SDK](/reference/sdks/python/overview), use the `upsert_from_dataframe` method. The method includes retry logic and`batch_size`, and is performant especially with Parquet file data sets.

The following example upserts the `uora_all-MiniLM-L6-bm25` dataset as a dataframe.

```Python Python theme={null}
from pinecone import Pinecone, ServerlessSpec
from pinecone_datasets import list_datasets, load_dataset

pc = Pinecone(api_key="API_KEY")

dataset = load_dataset("quora_all-MiniLM-L6-bm25")

pc.create_index(
  name="docs-example",
  dimension=384,
  metric="cosine",
  spec=ServerlessSpec(
    cloud="aws",
    region="us-east-1"
  )
)

# To get the unique host for an index, 
# see https://docs.pinecone.io/guides/manage-data/target-an-index
index = pc.Index(host="INDEX_HOST")

index.upsert_from_dataframe(dataset.drop(columns=["blob"]))
```


# Reference
Source: https://docs.pinecone.io/reference/sdks/python/reference

Reference documentation for the Pinecone Python SDK, including client setup, types, and methods for managing indexes and vector data operations.



# Spark-Pinecone connector
Source: https://docs.pinecone.io/reference/tools/pinecone-spark-connector

Pinecone data tools: Use the connector to efficiently create, ingest, and update vector embeddings at scale with Databricks and Pinecone.

Use the [`spark-pinecone` connector](https://github.com/pinecone-io/spark-pinecone/) to efficiently create, ingest, and update [vector embeddings](https://www.pinecone.io/learn/vector-embeddings/) at scale with [Databricks and Pinecone](/integrations/databricks).

## Install the Spark-Pinecone connector

<Tabs>
  <Tab title="Databricks platform">
    1. [Install the Spark-Pinecone connector as a library](https://docs.databricks.com/en/libraries/cluster-libraries.html#install-a-library-on-a-cluster).
    2. Configure the library as follows:
       1. Select **File path/S3** as the **Library Source**.

       2. Enter the S3 URI for the Pinecone assembly JAR file:

          ```
          s3://pinecone-jars/1.1.0/spark-pinecone-uberjar.jar  
          ```

          <Note>
            Databricks platform users must use the Pinecone assembly jar listed above to ensure that the proper dependecies are installed.
          </Note>

       3. Click **Install**.
  </Tab>

  <Tab title="Databricks on AWS">
    1. [Install the Spark-Pinecone connector as a library](https://docs.databricks.com/en/libraries/cluster-libraries.html#install-a-library-on-a-cluster).
    2. Configure the library as follows:
       1. Select **File path/S3** as the **Library Source**.

       2. Enter the S3 URI for the Pinecone assembly JAR file:

          ```
          s3://pinecone-jars/1.1.0/spark-pinecone-uberjar.jar  
          ```

       3. Click **Install**.
  </Tab>

  <Tab title="Databricks on GCP / Azure">
    1. [Install the Spark-Pinecone connector as a library](https://docs.databricks.com/en/libraries/cluster-libraries.html#install-a-library-on-a-cluster).
    2. Configure the library as follows:
       1. [Download the Pinecone assembly JAR file](https://repo1.maven.org/maven2/io/pinecone/spark-pinecone_2.12/1.1.0/).
       2. Select **Workspace** as the **Library Source**.
       3. Upload the JAR file.
       4. Click **Install**.
  </Tab>
</Tabs>

## Batch upsert

To batch upsert embeddings to Pinecone:

<CodeGroup>
  ```python Python theme={null}
  from pyspark import SparkConf
  from pyspark.sql import SparkSession
  from pyspark.sql.types import StructType, StructField, ArrayType, FloatType, StringType, LongType

  # Your API key and index name
  api_key = "PINECONE_API_KEY"
  index_name = "PINECONE_INDEX_NAME"
  source_tag = "PINECONE_SOURCE_TAG"

  COMMON_SCHEMA = StructType([
      StructField("id", StringType(), False),
      StructField("namespace", StringType(), True),
      StructField("values", ArrayType(FloatType(), False), False),
      StructField("metadata", StringType(), True),
      StructField("sparse_values", StructType([
          StructField("indices", ArrayType(LongType(), False), False),
          StructField("values", ArrayType(FloatType(), False), False)
      ]), True)
  ])

  # Initialize Spark
  spark = SparkSession.builder.getOrCreate()

  # Read the file and apply the schema
  df = spark.read \
      .option("multiLine", value = True) \
      .option("mode", "PERMISSIVE") \
      .schema(COMMON_SCHEMA) \
      .json("src/test/resources/sample.jsonl")

  # Show if the read was successful
  df.show()

  # Write the dataFrame to Pinecone in batches 
  df.write \
      .option("pinecone.apiKey", api_key) \
      .option("pinecone.indexName", index_name) \
      .option("pinecone.sourceTag", source_tag) \
      .format("io.pinecone.spark.pinecone.Pinecone") \
      .mode("append") \
      .save()
  ```

  ```scala Scala theme={null}
  import io.pinecone.spark.pinecone.{COMMON_SCHEMA, PineconeOptions}
  import org.apache.spark.SparkConf
  import org.apache.spark.sql.{SaveMode, SparkSession}

  object MainApp extends App {
    // Your API key and index name
    val apiKey = "PINECONE_API_KEY"
    val indexName = "PINECONE_INDEX_NAME"
    val sourceTag = "PINECONE_SOURCE_TAG"

    // Configure Spark to run locally with all available cores
    val conf = new SparkConf()
      .setMaster("local[*]")

    // Create a Spark session with the defined configuration
    val spark = SparkSession.builder().config(conf).getOrCreate()

    // Read the JSON file into a DataFrame, applying the COMMON_SCHEMA
    val df = spark.read
      .option("multiLine", value = true)
      .option("mode", "PERMISSIVE")
      .schema(COMMON_SCHEMA)
      .json("src/test/resources/sample.jsonl") // path to sample.jsonl

    // Define Pinecone options as a Map
    val pineconeOptions = Map(
      PineconeOptions.PINECONE_API_KEY_CONF -> apiKey,
      PineconeOptions.PINECONE_INDEX_NAME_CONF -> indexName,
      PineconeOptions.PINECONE_SOURCE_TAG_CONF -> sourceTag
    )

    // Show if the read was successful
    df.show(df.count().toInt)
    
    // Write the DataFrame to Pinecone using the defined options in batches
    df.write
      .options(pineconeOptions)
      .format("io.pinecone.spark.pinecone.Pinecone")
      .mode(SaveMode.Append)
      .save()
  }
  ```
</CodeGroup>

<Tip>
  For a guide on how to set up batch upserts, refer to the [Databricks integration page](/integrations/databricks#setup-guide).
</Tip>

## Stream upsert

To stream upsert embeddings to Pinecone:

<CodeGroup>
  ```python Python theme={null}
  from pyspark.sql import SparkSession
  from pyspark.sql.types import StructType, StructField, ArrayType, FloatType, StringType, LongType
  import os

  # Your API key and index name
  api_key = "PINECONE_API_KEY"
  index_name = "PINECONE_INDEX_NAME"
  source_tag = "PINECONE_SOURCE_TAG"

  COMMON_SCHEMA = StructType([
      StructField("id", StringType(), False),
      StructField("namespace", StringType(), True),
      StructField("values", ArrayType(FloatType(), False), False),
      StructField("metadata", StringType(), True),
      StructField("sparse_values", StructType([
          StructField("indices", ArrayType(LongType(), False), False),
          StructField("values", ArrayType(FloatType(), False), False)
      ]), True)
  ])

  # Initialize Spark session
  spark = SparkSession.builder \
      .appName("StreamUpsertExample") \
      .config("spark.sql.shuffle.partitions", 3) \
      .master("local") \
      .getOrCreate()

  # Read the stream of JSON files, applying the schema from the input directory
  lines = spark.readStream \
      .option("multiLine", True) \
      .option("mode", "PERMISSIVE") \
      .schema(COMMON_SCHEMA) \
      .json("path/to/input/directory/")

  # Write the stream to Pinecone using the defined options
  upsert = lines.writeStream \
      .format("io.pinecone.spark.pinecone.Pinecone") \
      .option("pinecone.apiKey", api_key) \
      .option("pinecone.indexName", index_name) \
      .option("pinecone.sourceTag", source_tag) \
      .option("checkpointLocation", "path/to/checkpoint/dir") \
      .outputMode("append") \
      .start()

  upsert.awaitTermination()
  ```

  ```scala Scala theme={null}
  import io.pinecone.spark.pinecone.{COMMON_SCHEMA, PineconeOptions}
  import org.apache.spark.SparkConf
  import org.apache.spark.sql.{SaveMode, SparkSession}

  object MainApp extends App {
    // Your API key and index name
    val apiKey = "PINECONE_API_KEY"
    val indexName = "PINECONE_INDEX_NAME"

    // Create a Spark session
    val spark = SparkSession.builder()
      .appName("StreamUpsertExample")
      .config("spark.sql.shuffle.partitions", 3)
      .master("local")
      .getOrCreate()

    // Read the JSON files into a DataFrame, applying the COMMON_SCHEMA from input directory
    val lines = spark.readStream
      .option("multiLine", value = true)
      .option("mode", "PERMISSIVE")
      .schema(COMMON_SCHEMA)
      .json("path/to/input/directory/")

    // Define Pinecone options as a Map
    val pineconeOptions = Map(
      PineconeOptions.PINECONE_API_KEY_CONF -> System.getenv("PINECONE_API_KEY"),
      PineconeOptions.PINECONE_INDEX_NAME_CONF -> System.getenv("PINECONE_INDEX"),
      PineconeOptions.PINECONE_SOURCE_TAG_CONF -> System.getenv("PINECONE_SOURCE_TAG")
    )

    // Write the stream to Pinecone using the defined options
    val upsert = lines
      .writeStream
      .format("io.pinecone.spark.pinecone.Pinecone")
      .options(pineconeOptions)
      .option("checkpointLocation", "path/to/checkpoint/dir")
      .outputMode("append")
      .start()

    upsert.awaitTermination()
  }
  ```
</CodeGroup>

## Learn more

* [Spark-Pinecone connector setup guide](/integrations/databricks#setup-guide)
* [GitHub](https://github.com/pinecone-io/spark-pinecone)


# Create an API key
Source: https://docs.pinecone.io/reference/api/2026-04/admin/create_api_key

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml post /admin/projects/{project_id}/api-keys
Create an API key for a project to authenticate Data Plane and Control Plane requests.


<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  const apiKey = await admin.apiKeys.create('YOUR_PROJECT_ID', {
    name: 'Example API Key',
    roles: ['ProjectEditor'],
  });

  // `apiKey.value` is returned only at creation time and cannot be retrieved
  // later. Store it securely and never log it.
  console.log(apiKey.key);
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "fmt"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      roles := []string{"ProjectEditor"}
      apiKey, err := adminClient.APIKey.Create(ctx, "YOUR_PROJECT_ID", &pinecone.CreateAPIKeyParams{
          Name:  "Example API Key",
          Roles: &roles,
      })
      if err != nil {
          log.Fatalf("Failed to create API key: %v", err)
      }
      // Value is returned only at creation time — store it securely and never log it
      fmt.Printf("Successfully created API key: %v\n", apiKey.Key.Id)
  }
  ```

  ```hcl Terraform theme={null}
  # Requires Terraform provider v4.0.0 or later
  resource "pinecone_api_key" "example" {
    name       = "Example API Key"
    project_id = "YOUR_PROJECT_ID"
    roles      = ["ProjectEditor"]
  }
  ```

  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
  PINECONE_PROJECT_ID="YOUR_PROJECT_ID"

  curl "https://api.pinecone.io/admin/projects/$PINECONE_PROJECT_ID/api-keys" \
  	-H "X-Pinecone-Api-Version: 2026-04" \
  	-H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
  	-d '{
  		"name": "Example API Key",
  		"roles": ["ProjectEditor"]
  	}'
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "key": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Example API key",
      "project_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "roles": [
        "ProjectEditor"
      ]
    },
    "value": "string"
  }
  ```
</ResponseExample>


# Invite a user to the organization
Source: https://docs.pinecone.io/reference/api/2026-04/admin/create_invite

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml post /admin/invites
Invite a user to the organization by email and grant their initial role bindings.


<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  const invite = await admin.invites.create({
    email: 'newhire@example.com',
    roleBindings: [
      { resourceType: 'organization', role: 'OrgMember' },
      {
        resourceType: 'project',
        resourceId: 'a2f7dddb-1597-4eff-9f71-535fde243f58',
        role: 'ProjectMember',
      },
    ],
  });
  console.log(invite);
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "fmt"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      projectId := "a2f7dddb-1597-4eff-9f71-535fde243f58"
      invite, err := adminClient.Invite.Create(ctx, &pinecone.CreateInviteParams{
          Email: "newhire@example.com",
          RoleBindings: []pinecone.RoleBindingInput{
              {ResourceType: pinecone.ResourceTypeOrganization, Role: "OrgMember"},
              {ResourceType: pinecone.ResourceTypeProject, ResourceId: &projectId, Role: "ProjectMember"},
          },
      })
      if err != nil {
          log.Fatalf("Failed to create invite: %v", err)
      }
      fmt.Printf("Invited %v (status: %v)\n", invite.Email, invite.Status)
  }
  ```

  ```hcl Terraform theme={null}
  # Requires Terraform provider v4.0.0 or later
  resource "pinecone_invite" "newhire" {
    email = "newhire@example.com"

    role_bindings = [
      {
        resource_type = "organization"
        role          = "OrgMember"
      },
      {
        resource_type = "project"
        resource_id   = "a2f7dddb-1597-4eff-9f71-535fde243f58"
        role          = "ProjectMember"
      }
    ]
  }
  ```

  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

  curl "https://api.pinecone.io/admin/invites" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "X-Pinecone-Api-Version: 2026-04" \
    -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
    -d '{
      "email": "newhire@example.com",
      "role_bindings": [
        {
          "resource_type": "organization",
          "role": "OrgMember"
        },
        {
          "resource_type": "project",
          "resource_id": "a2f7dddb-1597-4eff-9f71-535fde243f58",
          "role": "ProjectMember"
        }
      ]
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "id": "9c8e3528-b9c0-4358-84ce-84c28e91b566",
    "email": "newhire@example.com",
    "status": "pending",
    "expires_at": "2026-05-21T03:00:00Z",
    "processed_at": null,
    "created_at": "2026-04-14T20:00:00Z"
  }
  ```
</ResponseExample>


# Create a new project
Source: https://docs.pinecone.io/reference/api/2026-04/admin/create_project

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml post /admin/projects
Create a new project.

<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  const project = await admin.projects.create({ name: 'example-project' });
  console.log(project);
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "fmt"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      project, err := adminClient.Project.Create(ctx, &pinecone.CreateProjectParams{
          Name: "example-project",
      })
      if err != nil {
          log.Fatalf("Failed to create project: %v", err)
      }
      fmt.Printf("Successfully created project: %v\n", project.Id)
  }
  ```

  ```hcl Terraform theme={null}
  # Requires Terraform provider v4.0.0 or later
  resource "pinecone_project" "example" {
    name = "example-project"
  }
  ```

  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

  curl "https://api.pinecone.io/admin/projects" \
      -H "X-Pinecone-Api-Version: 2026-04" \
  	-H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
  	-d '{
          "name":"example-project"
          }'
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "example-project",
    "max_pods": 0,
    "force_encryption_with_cmek": false,
    "organization_id": "string",
    "created_at": "2025-03-16T22:46:45.030Z"
  }
  ```
</ResponseExample>


# Create a role binding
Source: https://docs.pinecone.io/reference/api/2026-04/admin/create_role_binding

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml post /admin/role-bindings
Grant a role to a principal at an organization or project scope.


<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  const roleBinding = await admin.roleBindings.create({
    principalType: 'service_account',
    principalId: 'f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c',
    resourceType: 'project',
    resourceId: 'a2f7dddb-1597-4eff-9f71-535fde243f58',
    role: 'DataPlaneEditor',
  });
  console.log(roleBinding);
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "fmt"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      projectId := "a2f7dddb-1597-4eff-9f71-535fde243f58"
      roleBinding, err := adminClient.RoleBinding.Create(ctx, &pinecone.CreateRoleBindingParams{
          PrincipalType: pinecone.PrincipalTypeServiceAccount,
          PrincipalId:   "f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
          ResourceType:  pinecone.ResourceTypeProject,
          ResourceId:    &projectId,
          Role:          "DataPlaneEditor",
      })
      if err != nil {
          log.Fatalf("Failed to create role binding: %v", err)
      }
      fmt.Printf("Successfully created role binding: %v\n", roleBinding.Id)
  }
  ```

  ```hcl Terraform theme={null}
  # Requires Terraform provider v4.0.0 or later
  # Bindings are immutable; changing any attribute forces replacement
  resource "pinecone_role_binding" "ci_data_plane_editor" {
    principal_type = "service_account"
    principal_id   = "f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c"
    resource_type  = "project"
    resource_id    = "a2f7dddb-1597-4eff-9f71-535fde243f58"
    role           = "DataPlaneEditor"
  }
  ```

  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

  curl "https://api.pinecone.io/admin/role-bindings" \
  	-H "X-Pinecone-Api-Version: 2026-04" \
  	-H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
  	-d '{
  		"principal_type": "service_account",
  		"principal_id": "f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
  		"resource_type": "project",
  		"resource_id": "a2f7dddb-1597-4eff-9f71-535fde243f58",
  		"role": "DataPlaneEditor"
  	}'
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "id": "9a8e3528-b9c0-4358-84ce-84c28e91b566",
    "principal_type": "service_account",
    "principal_id": "f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
    "resource_type": "project",
    "resource_id": "a2f7dddb-1597-4eff-9f71-535fde243f58",
    "role": "DataPlaneEditor",
    "created_at": "2026-04-10T15:23:00Z"
  }
  ```
</ResponseExample>


# Create a service account
Source: https://docs.pinecone.io/reference/api/2026-04/admin/create_service_account

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml post /admin/service-accounts
Create a service account with optional initial role bindings; the client secret is returned only once.


<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  // `clientSecret` is returned only once and cannot be retrieved later
  const { serviceAccount, clientSecret } = await admin.serviceAccounts.create({
    name: 'ci-prod',
    roleBindings: [
      {
        resourceType: 'project',
        resourceId: 'a2f7dddb-1597-4eff-9f71-535fde243f58',
        role: 'DataPlaneEditor',
      },
    ],
  });
  console.log(serviceAccount);
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "fmt"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      projectId := "a2f7dddb-1597-4eff-9f71-535fde243f58"
      sa, err := adminClient.ServiceAccount.Create(ctx, &pinecone.CreateServiceAccountParams{
          Name: "ci-prod",
          RoleBindings: []pinecone.RoleBindingInput{
              {
                  ResourceType: pinecone.ResourceTypeProject,
                  ResourceId:   &projectId,
                  Role:         "DataPlaneEditor",
              },
          },
      })
      if err != nil {
          log.Fatalf("Failed to create service account: %v", err)
      }
      // ClientSecret is returned only once — store it securely and never log it
      fmt.Printf("Successfully created service account: %v\n", sa.ServiceAccount.Id)
  }
  ```

  ```hcl Terraform theme={null}
  # Requires Terraform provider v4.0.0 or later
  # Roles are assigned with separate pinecone_role_binding resources
  resource "pinecone_service_account" "ci_prod" {
    name = "ci-prod"
  }

  resource "pinecone_role_binding" "ci_prod_data_plane_editor" {
    principal_id   = pinecone_service_account.ci_prod.id
    principal_type = "service_account"
    resource_type  = "project"
    resource_id    = "a2f7dddb-1597-4eff-9f71-535fde243f58"
    role           = "DataPlaneEditor"
  }

  output "ci_prod_client_secret" {
    value     = pinecone_service_account.ci_prod.client_secret
    sensitive = true
  }
  ```

  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

  curl "https://api.pinecone.io/admin/service-accounts" \
  	-H "X-Pinecone-Api-Version: 2026-04" \
  	-H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
  	-d '{
  		"name": "ci-prod",
  		"role_bindings": [
  			{
  				"resource_type": "project",
  				"resource_id": "a2f7dddb-1597-4eff-9f71-535fde243f58",
  				"role": "DataPlaneEditor"
  			}
  		]
  	}'
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "service_account": {
      "id": "f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
      "name": "ci-prod",
      "client_id": "l3Ow0CmFyc4jOONcwiKUCRqQKN0tiCAn",
      "created_at": "2026-04-10T15:23:00Z",
      "updated_at": "2026-04-10T15:23:00Z"
    },
    "client_secret": "8p-kkC23XOWvkCosKq-BOn3G74qp__rBcDMxc82iB4gfzRvuhSCRBKM7C5Q7TAzj"
  }
  ```
</ResponseExample>


# Delete an API key
Source: https://docs.pinecone.io/reference/api/2026-04/admin/delete_api_key

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml delete /admin/api-keys/{api_key_id}
Delete an API key from a project.

<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  await admin.apiKeys.delete('YOUR_API_KEY_ID');
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      if err := adminClient.APIKey.Delete(ctx, "YOUR_API_KEY_ID"); err != nil {
          log.Fatalf("Failed to delete API key: %v", err)
      }
  }
  ```

  ```hcl Terraform theme={null}
  # Requires Terraform provider v4.0.0 or later
  # This block defines the API key. To delete it, either remove the block and run
  # `terraform apply`, or run:
  #   terraform destroy -target=pinecone_api_key.example
  resource "pinecone_api_key" "example" {
    name       = "Example API Key"
    project_id = "YOUR_PROJECT_ID"
  }
  ```

  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
  PINECONE_API_KEY_ID="YOUR_KEY_ID"

  curl -X DELETE "https://api.pinecone.io/admin/api-keys/$PINECONE_API_KEY_ID" \
  	-H "X-Pinecone-Api-Version: 2026-04" \
  	-H "Authorization: Bearer $PINECONE_ACCESS_TOKEN"
  ```
</RequestExample>


# Delete an invite
Source: https://docs.pinecone.io/reference/api/2026-04/admin/delete_invite

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml delete /admin/invites/{invite_id}
Delete a pending or expired invite and its role bindings; to remove an accepted user, delete the user instead.


<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  await admin.invites.delete('YOUR_INVITE_ID');
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      if err := adminClient.Invite.Delete(ctx, "YOUR_INVITE_ID"); err != nil {
          log.Fatalf("Failed to delete invite: %v", err)
      }
  }
  ```

  ```hcl Terraform theme={null}
  # Requires Terraform provider v4.0.0 or later
  # This block defines the invite. To revoke a pending invite, either remove the
  # block and run `terraform apply`, or run:
  #   terraform destroy -target=pinecone_invite.newhire
  resource "pinecone_invite" "newhire" {
    email = "newhire@example.com"

    role_bindings = [
      {
        resource_type = "organization"
        role          = "OrgMember"
      }
    ]
  }
  ```

  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
  PINECONE_INVITE_ID="YOUR_INVITE_ID"

  curl -X DELETE "https://api.pinecone.io/admin/invites/$PINECONE_INVITE_ID" \
  	-H "X-Pinecone-Api-Version: 2026-04" \
  	-H "Authorization: Bearer $PINECONE_ACCESS_TOKEN"
  ```
</RequestExample>


# Delete a project
Source: https://docs.pinecone.io/reference/api/2026-04/admin/delete_project

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml delete /admin/projects/{project_id}
Delete a project and all its configuration; delete its indexes, assistants, backups, and collections first.


<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  await admin.projects.delete('YOUR_PROJECT_ID');
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      if err := adminClient.Project.Delete(ctx, "YOUR_PROJECT_ID"); err != nil {
          log.Fatalf("Failed to delete project: %v", err)
      }
  }
  ```

  ```hcl Terraform theme={null}
  # Requires Terraform provider v4.0.0 or later
  # This block defines the project. To delete it, either remove the block and run
  # `terraform apply`, or run:
  #   terraform destroy -target=pinecone_project.example
  resource "pinecone_project" "example" {
    name = "example-project"
  }
  ```

  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
  PROJECT_ID="YOUR_PROJECT_ID"

  curl -X DELETE "https://api.pinecone.io/admin/projects/$PROJECT_ID" \
  	-H "X-Pinecone-Api-Version: 2026-04" \
  	-H "Authorization: Bearer $PINECONE_ACCESS_TOKEN"
  ```
</RequestExample>


# Delete a role binding
Source: https://docs.pinecone.io/reference/api/2026-04/admin/delete_role_binding

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml delete /admin/role-bindings/{role_binding_id}
Delete a role binding; permissions are revoked when the deletion completes.


<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  await admin.roleBindings.delete('YOUR_ROLE_BINDING_ID');
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      if err := adminClient.RoleBinding.Delete(ctx, "YOUR_ROLE_BINDING_ID"); err != nil {
          log.Fatalf("Failed to delete role binding: %v", err)
      }
  }
  ```

  ```hcl Terraform theme={null}
  # Requires Terraform provider v4.0.0 or later
  # This block defines the role binding. To revoke the role, either remove the
  # block and run `terraform apply`, or run:
  #   terraform destroy -target=pinecone_role_binding.ci_data_plane_editor
  resource "pinecone_role_binding" "ci_data_plane_editor" {
    principal_type = "service_account"
    principal_id   = "f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c"
    resource_type  = "project"
    resource_id    = "a2f7dddb-1597-4eff-9f71-535fde243f58"
    role           = "DataPlaneEditor"
  }
  ```

  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
  PINECONE_ROLE_BINDING_ID="YOUR_ROLE_BINDING_ID"

  curl -X DELETE "https://api.pinecone.io/admin/role-bindings/$PINECONE_ROLE_BINDING_ID" \
  	-H "X-Pinecone-Api-Version: 2026-04" \
  	-H "Authorization: Bearer $PINECONE_ACCESS_TOKEN"
  ```
</RequestExample>


# Delete a service account
Source: https://docs.pinecone.io/reference/api/2026-04/admin/delete_service_account

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml delete /admin/service-accounts/{service_account_id}
Delete a service account and its role bindings; tokens it minted are revoked within a few seconds.


<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  await admin.serviceAccounts.delete('YOUR_SERVICE_ACCOUNT_ID');
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      if err := adminClient.ServiceAccount.Delete(ctx, "YOUR_SERVICE_ACCOUNT_ID"); err != nil {
          log.Fatalf("Failed to delete service account: %v", err)
      }
  }
  ```

  ```hcl Terraform theme={null}
  # Requires Terraform provider v4.0.0 or later
  # This block defines the service account. To delete it, either remove the block
  # and run `terraform apply`, or run:
  #   terraform destroy -target=pinecone_service_account.ci_prod
  resource "pinecone_service_account" "ci_prod" {
    name = "ci-prod"
  }
  ```

  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
  PINECONE_SERVICE_ACCOUNT_ID="YOUR_SERVICE_ACCOUNT_ID"

  curl -X DELETE "https://api.pinecone.io/admin/service-accounts/$PINECONE_SERVICE_ACCOUNT_ID" \
  	-H "X-Pinecone-Api-Version: 2026-04" \
  	-H "Authorization: Bearer $PINECONE_ACCESS_TOKEN"
  ```
</RequestExample>


# Remove a user from the organization
Source: https://docs.pinecone.io/reference/api/2026-04/admin/delete_user

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml delete /admin/users/{user_id}
Remove a user from the organization and revoke their role bindings; their Pinecone account is not deleted.


<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  await admin.users.delete('YOUR_USER_ID');
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      if err := adminClient.User.Delete(ctx, "YOUR_USER_ID"); err != nil {
          log.Fatalf("Failed to delete user: %v", err)
      }
  }
  ```

  ```hcl Terraform theme={null}
  # Requires Terraform provider v4.0.0 or later
  # Users join by accepting an invite, so import the existing member first:
  #   terraform import pinecone_user.teammate YOUR_USER_ID
  # Then remove the resource block and run `terraform apply` to remove them
  # from the organization.
  resource "pinecone_user" "teammate" {
    id = "YOUR_USER_ID"
  }
  ```

  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
  PINECONE_USER_ID="YOUR_USER_ID"

  curl -X DELETE "https://api.pinecone.io/admin/users/$PINECONE_USER_ID" \
  	-H "X-Pinecone-Api-Version: 2026-04" \
  	-H "Authorization: Bearer $PINECONE_ACCESS_TOKEN"
  ```
</RequestExample>


# Get API key details
Source: https://docs.pinecone.io/reference/api/2026-04/admin/fetch_api_key

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml get /admin/api-keys/{api_key_id}
Get an API key's details, excluding its secret.

<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  const apiKey = await admin.apiKeys.describe('YOUR_API_KEY_ID');
  console.log(apiKey);
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "fmt"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      apiKey, err := adminClient.APIKey.Describe(ctx, "YOUR_API_KEY_ID")
      if err != nil {
          log.Fatalf("Failed to describe API key: %v", err)
      }
      fmt.Printf("API key: %v (%v)\n", apiKey.Name, apiKey.Id)
  }
  ```

  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
  PINECONE_API_KEY_ID="3fa85f64-5717-4562-b3fc-2c963f66afa6"

  curl -X GET "https://api.pinecone.io/admin/api-keys/$PINECONE_API_KEY_ID" \
  	-H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
      -H "accept: application/json" \
      -H "X-Pinecone-Api-Version: 2026-04"
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "string",
    "project_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "roles": [
      "ProjectEditor"
    ]
  }
  ```
</ResponseExample>


# Get invite details
Source: https://docs.pinecone.io/reference/api/2026-04/admin/fetch_invite

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml get /admin/invites/{invite_id}
Get an invite in the caller's organization by ID.

<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  const invite = await admin.invites.describe('YOUR_INVITE_ID');
  console.log(invite);
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "fmt"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      invite, err := adminClient.Invite.Describe(ctx, "YOUR_INVITE_ID")
      if err != nil {
          log.Fatalf("Failed to describe invite: %v", err)
      }
      fmt.Printf("Invite: %v (status: %v)\n", invite.Email, invite.Status)
  }
  ```

  ```hcl Terraform theme={null}
  # Requires Terraform provider v4.0.0 or later
  data "pinecone_invite" "example" {
    id = "YOUR_INVITE_ID"
  }

  output "invite_status" {
    value = data.pinecone_invite.example.status
  }
  ```

  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
  PINECONE_INVITE_ID="9c8e3528-b9c0-4358-84ce-84c28e91b566"

  curl -X GET "https://api.pinecone.io/admin/invites/$PINECONE_INVITE_ID" \
  	-H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
  	-H "accept: application/json" \
  	-H "X-Pinecone-Api-Version: 2026-04"
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "id": "9c8e3528-b9c0-4358-84ce-84c28e91b566",
    "email": "newhire@example.com",
    "status": "pending",
    "expires_at": "2026-05-21T03:00:00Z",
    "processed_at": null,
    "created_at": "2026-04-14T20:00:00Z"
  }
  ```
</ResponseExample>


# Get project details
Source: https://docs.pinecone.io/reference/api/2026-04/admin/fetch_project

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml get /admin/projects/{project_id}
Get a project's details.

<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  const project = await admin.projects.describe('YOUR_PROJECT_ID');
  console.log(project);
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "fmt"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      project, err := adminClient.Project.Describe(ctx, "YOUR_PROJECT_ID")
      if err != nil {
          log.Fatalf("Failed to describe project: %v", err)
      }
      fmt.Printf("Project: %v (%v)\n", project.Name, project.Id)
  }
  ```

  ```hcl Terraform theme={null}
  # Requires Terraform provider v4.0.0 or later
  data "pinecone_project" "example" {
    id = "YOUR_PROJECT_ID"
  }

  output "project_name" {
    value = data.pinecone_project.example.name
  }
  ```

  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
  PROJECT_ID="3fa85f64-5717-4562-b3fc-2c963f66afa6"

  curl -X GET "https://api.pinecone.io/admin/projects/$PROJECT_ID" \
      -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
  	-H "X-Pinecone-Api-Version: 2026-04" \
      -H "accept: application/json"
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "example-project",
    "max_pods": 0,
    "force_encryption_with_cmek": false,
    "organization_id": "string",
    "created_at": "2025-03-17T00:30:23.262Z"
  }
  ```
</ResponseExample>


# Get role binding details
Source: https://docs.pinecone.io/reference/api/2026-04/admin/fetch_role_binding

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml get /admin/role-bindings/{role_binding_id}
Get a role binding in the caller's organization by ID.


<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  const roleBinding = await admin.roleBindings.describe('YOUR_ROLE_BINDING_ID');
  console.log(roleBinding);
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "fmt"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      roleBinding, err := adminClient.RoleBinding.Describe(ctx, "YOUR_ROLE_BINDING_ID")
      if err != nil {
          log.Fatalf("Failed to describe role binding: %v", err)
      }
      fmt.Printf("Role binding: %v (%v)\n", roleBinding.Role, roleBinding.Id)
  }
  ```

  ```hcl Terraform theme={null}
  # Requires Terraform provider v4.0.0 or later
  data "pinecone_role_binding" "example" {
    id = "YOUR_ROLE_BINDING_ID"
  }

  output "role" {
    value = data.pinecone_role_binding.example.role
  }
  ```

  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
  PINECONE_ROLE_BINDING_ID="9a8e3528-b9c0-4358-84ce-84c28e91b566"

  curl -X GET "https://api.pinecone.io/admin/role-bindings/$PINECONE_ROLE_BINDING_ID" \
  	-H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
  	-H "accept: application/json" \
  	-H "X-Pinecone-Api-Version: 2026-04"
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "id": "9a8e3528-b9c0-4358-84ce-84c28e91b566",
    "principal_type": "service_account",
    "principal_id": "f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
    "resource_type": "project",
    "resource_id": "a2f7dddb-1597-4eff-9f71-535fde243f58",
    "role": "DataPlaneEditor",
    "created_at": "2026-04-10T15:23:00Z"
  }
  ```
</ResponseExample>


# Get service account details
Source: https://docs.pinecone.io/reference/api/2026-04/admin/fetch_service_account

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml get /admin/service-accounts/{service_account_id}
Get a service account by ID; the client secret is returned only from create and rotate-secret requests.


<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  const serviceAccount = await admin.serviceAccounts.describe('YOUR_SERVICE_ACCOUNT_ID');
  console.log(serviceAccount);
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "fmt"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      sa, err := adminClient.ServiceAccount.Describe(ctx, "YOUR_SERVICE_ACCOUNT_ID")
      if err != nil {
          log.Fatalf("Failed to describe service account: %v", err)
      }
      fmt.Printf("Service account: %v (%v)\n", sa.Name, sa.Id)
  }
  ```

  ```hcl Terraform theme={null}
  # Requires Terraform provider v4.0.0 or later
  data "pinecone_service_account" "example" {
    id = "YOUR_SERVICE_ACCOUNT_ID"
  }

  output "service_account_name" {
    value = data.pinecone_service_account.example.name
  }
  ```

  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
  PINECONE_SERVICE_ACCOUNT_ID="f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c"

  curl -X GET "https://api.pinecone.io/admin/service-accounts/$PINECONE_SERVICE_ACCOUNT_ID" \
  	-H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
  	-H "accept: application/json" \
  	-H "X-Pinecone-Api-Version: 2026-04"
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "id": "f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
    "name": "My Service Account",
    "client_id": "l3Ow0CmFyc4jOONcwiKUCRqQKN0tiCAn",
    "created_at": "2026-04-10T15:23:00Z",
    "updated_at": "2026-04-12T09:11:00Z"
  }
  ```
</ResponseExample>


# Get user details
Source: https://docs.pinecone.io/reference/api/2026-04/admin/fetch_user

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml get /admin/users/{user_id}
Get a user in the caller's organization by ID.

<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  const user = await admin.users.describe('YOUR_USER_ID');
  console.log(user);
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "fmt"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      user, err := adminClient.User.Describe(ctx, "YOUR_USER_ID")
      if err != nil {
          log.Fatalf("Failed to describe user: %v", err)
      }
      fmt.Printf("User: %v (%v)\n", user.Email, user.Id)
  }
  ```

  ```hcl Terraform theme={null}
  # Requires Terraform provider v4.0.0 or later
  # Look up a user by id or by email
  data "pinecone_user" "example" {
    id = "YOUR_USER_ID"
  }

  output "user_name" {
    value = data.pinecone_user.example.name
  }
  ```

  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
  PINECONE_USER_ID="e2e92523-85dc-4142-b8c2-e681be8b78df"

  curl -X GET "https://api.pinecone.io/admin/users/$PINECONE_USER_ID" \
  	-H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
  	-H "accept: application/json" \
  	-H "X-Pinecone-Api-Version: 2026-04"
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "id": "e2e92523-85dc-4142-b8c2-e681be8b78df",
    "email": "alice@example.com",
    "name": "Alice Example",
    "created_at": "2026-04-10T15:23:00Z",
    "updated_at": "2026-04-12T09:11:00Z"
  }
  ```
</ResponseExample>


# Create an access token
Source: https://docs.pinecone.io/reference/api/2026-04/admin/get_token

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/oauth_2026-04.oas.yaml post /oauth/token
Obtain an access token for a service account using the OAuth2 client credentials flow. An access token is needed to authorize requests to the Pinecone Admin API.
The host domain for OAuth endpoints is `login.pinecone.io`.


<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // You don't call this endpoint directly when using the SDK. The AdminClient
  // exchanges your service account credentials for an access token on the first
  // admin request and reuses it for subsequent calls.
  const admin = new AdminClient({
    clientId: 'YOUR_CLIENT_ID',
    clientSecret: 'YOUR_CLIENT_SECRET',
  });

  const { data: projects } = await admin.projects.list();
  console.log(projects);
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "fmt"
      "log"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      // You don't call this endpoint directly when using the SDK. The AdminClient
      // exchanges your service account credentials for an access token.
      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     "YOUR_CLIENT_ID",
          ClientSecret: "YOUR_CLIENT_SECRET",
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      projects, err := adminClient.Project.List(ctx)
      if err != nil {
          log.Fatalf("Failed to list projects: %v", err)
      }
      fmt.Printf("Found %v projects\n", len(projects))
  }
  ```

  ```bash curl theme={null}
  curl "https://login.pinecone.io/oauth/token" \ # Note: Base URL is login.pinecone.io
  	-H "X-Pinecone-Api-Version: 2026-04" \
  	-H "Content-Type: application/json" \
  	-d '{
  		"grant_type": "client_credentials",
  		"client_id": "YOUR_CLIENT_ID",
  		"client_secret": "YOUR_CLIENT_SECRET",
  		"audience": "https://api.pinecone.io/"
  	}'
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
      "access_token":"YOUR_ACCESS_TOKEN",
      "expires_in":86400,
      "token_type":"Bearer"
  }
  ```
</ResponseExample>


# List API keys
Source: https://docs.pinecone.io/reference/api/2026-04/admin/list_api_keys

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml get /admin/projects/{project_id}/api-keys
List all API keys in a project.

<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  const { data: apiKeys } = await admin.apiKeys.list('YOUR_PROJECT_ID');
  console.log(apiKeys);
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "fmt"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      apiKeys, err := adminClient.APIKey.List(ctx, "YOUR_PROJECT_ID")
      if err != nil {
          log.Fatalf("Failed to list API keys: %v", err)
      }
      for _, apiKey := range apiKeys {
          fmt.Printf("API key: %v (%v)\n", apiKey.Name, apiKey.Id)
      }
  }
  ```

  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
  PINECONE_PROJECT_ID="YOUR_PROJECT_ID"

  curl -X GET "https://api.pinecone.io/admin/projects/$PINECONE_PROJECT_ID/api-keys" \
      -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
      -H "X-Pinecone-Api-Version: 2026-04"
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "data": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "name": "string",
        "project_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "roles": [
          "ProjectEditor"
        ]
      }
    ]
  }
  ```
</ResponseExample>


# List invites
Source: https://docs.pinecone.io/reference/api/2026-04/admin/list_invites

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml get /admin/invites
List pending and expired invites in the caller's organization.

<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  const { data: invites } = await admin.invites.list();
  console.log(invites);
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "fmt"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      invites, err := adminClient.Invite.List(ctx, &pinecone.ListInvitesParams{})
      if err != nil {
          log.Fatalf("Failed to list invites: %v", err)
      }
      for _, invite := range invites.Data {
          fmt.Printf("Invite: %v (status: %v)\n", invite.Email, invite.Status)
      }
  }
  ```

  ```hcl Terraform theme={null}
  # Requires Terraform provider v4.0.0 or later
  data "pinecone_invites" "all" {}

  output "invite_emails" {
    value = [for invite in data.pinecone_invites.all.invites : invite.email]
  }
  ```

  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

  curl -X GET "https://api.pinecone.io/admin/invites" \
  	-H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
  	-H "accept: application/json" \
  	-H "X-Pinecone-Api-Version: 2026-04"
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "data": [
      {
        "id": "9c8e3528-b9c0-4358-84ce-84c28e91b566",
        "email": "newhire@example.com",
        "status": "pending",
        "expires_at": "2026-05-21T03:00:00Z",
        "processed_at": null,
        "created_at": "2026-04-14T20:00:00Z"
      }
    ],
    "pagination": {
      "next": "eyJsYXN0X2lkIjoiOWM4ZTM1MjgifQ=="
    }
  }
  ```
</ResponseExample>


# List projects
Source: https://docs.pinecone.io/reference/api/2026-04/admin/list_projects

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml get /admin/projects
List all projects in an organization.

<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  const { data: projects } = await admin.projects.list();
  console.log(projects);
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "fmt"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      projects, err := adminClient.Project.List(ctx)
      if err != nil {
          log.Fatalf("Failed to list projects: %v", err)
      }
      for _, project := range projects {
          fmt.Printf("Project: %v (%v)\n", project.Name, project.Id)
      }
  }
  ```

  ```hcl Terraform theme={null}
  # Requires Terraform provider v4.0.0 or later
  data "pinecone_projects" "all" {}

  output "project_names" {
    value = [for project in data.pinecone_projects.all.projects : project.name]
  }
  ```

  ```bash curl theme={null}
  curl -X GET "https://api.pinecone.io/admin/projects" \
      -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
      -H "X-Pinecone-Api-Version: 2026-04"
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "data": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "name": "example-project",
        "max_pods": 0,
        "force_encryption_with_cmek": true,
        "organization_id": "<string>",
        "created_at": "2023-11-07T05:31:56Z"
      }
    ]
  }
  ```
</ResponseExample>


# List role bindings
Source: https://docs.pinecone.io/reference/api/2026-04/admin/list_role_bindings

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml get /admin/role-bindings
List role bindings in the caller's organization, optionally filtered by principal, resource, and role.


<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  const { data: roleBindings } = await admin.roleBindings.list({
    principalType: 'user',
    principalId: 'e2e92523-85dc-4142-b8c2-e681be8b78df',
  });
  console.log(roleBindings);
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "fmt"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      principalType := pinecone.PrincipalTypeUser
      principalId := "e2e92523-85dc-4142-b8c2-e681be8b78df"
      roleBindings, err := adminClient.RoleBinding.List(ctx, &pinecone.ListRoleBindingsParams{
          PrincipalType: &principalType,
          PrincipalId:   &principalId,
      })
      if err != nil {
          log.Fatalf("Failed to list role bindings: %v", err)
      }
      for _, roleBinding := range roleBindings.Data {
          fmt.Printf("Role binding: %v (%v)\n", roleBinding.Role, roleBinding.Id)
      }
  }
  ```

  ```hcl Terraform theme={null}
  # Requires Terraform provider v4.0.0 or later
  data "pinecone_role_bindings" "user_roles" {
    principal_type = "user"
    principal_id   = "e2e92523-85dc-4142-b8c2-e681be8b78df"
  }

  output "user_roles" {
    value = [for b in data.pinecone_role_bindings.user_roles.role_bindings : b.role]
  }
  ```

  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

  curl -X GET "https://api.pinecone.io/admin/role-bindings?principal_type=user&principal_id=e2e92523-85dc-4142-b8c2-e681be8b78df" \
  	-H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
  	-H "accept: application/json" \
  	-H "X-Pinecone-Api-Version: 2026-04"
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "data": [
      {
        "id": "5a86ed21-daf1-448d-a9ca-f92a0fd839d3",
        "principal_type": "user",
        "principal_id": "e2e92523-85dc-4142-b8c2-e681be8b78df",
        "resource_type": "organization",
        "resource_id": "-ExampleOrgId0000000",
        "role": "OrgMember",
        "created_at": "2026-04-10T15:23:00Z"
      }
    ],
    "pagination": {
      "next": "eyJsYXN0X2lkIjoiNWE4NmVkMjEifQ=="
    }
  }
  ```
</ResponseExample>


# List service accounts
Source: https://docs.pinecone.io/reference/api/2026-04/admin/list_service_accounts

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml get /admin/service-accounts
List service accounts in the caller's organization.

<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  const { data: serviceAccounts } = await admin.serviceAccounts.list();
  console.log(serviceAccounts);
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "fmt"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      serviceAccounts, err := adminClient.ServiceAccount.List(ctx, &pinecone.ListServiceAccountsParams{})
      if err != nil {
          log.Fatalf("Failed to list service accounts: %v", err)
      }
      for _, sa := range serviceAccounts.Data {
          fmt.Printf("Service account: %v (%v)\n", sa.Name, sa.Id)
      }
  }
  ```

  ```hcl Terraform theme={null}
  # Requires Terraform provider v4.0.0 or later
  data "pinecone_service_accounts" "all" {}

  output "service_account_names" {
    value = [for sa in data.pinecone_service_accounts.all.service_accounts : sa.name]
  }
  ```

  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

  curl -X GET "https://api.pinecone.io/admin/service-accounts" \
  	-H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
  	-H "accept: application/json" \
  	-H "X-Pinecone-Api-Version: 2026-04"
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "data": [
      {
        "id": "f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
        "name": "My Service Account",
        "client_id": "l3Ow0CmFyc4jOONcwiKUCRqQKN0tiCAn",
        "created_at": "2026-04-10T15:23:00Z",
        "updated_at": "2026-04-12T09:11:00Z"
      }
    ],
    "pagination": {
      "next": "eyJsYXN0X2lkIjoiZDI0MTc3YTAifQ=="
    }
  }
  ```
</ResponseExample>


# List users in the organization
Source: https://docs.pinecone.io/reference/api/2026-04/admin/list_users

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml get /admin/users
List users in the caller's organization, optionally filtered by email address.


<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  const { data: users } = await admin.users.list();
  console.log(users);
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "fmt"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      users, err := adminClient.User.List(ctx, &pinecone.ListUsersParams{})
      if err != nil {
          log.Fatalf("Failed to list users: %v", err)
      }
      for _, user := range users.Data {
          fmt.Printf("User: %v (%v)\n", user.Email, user.Id)
      }
  }
  ```

  ```hcl Terraform theme={null}
  # Requires Terraform provider v4.0.0 or later
  data "pinecone_users" "all" {}

  output "user_emails" {
    value = [for user in data.pinecone_users.all.users : user.email]
  }
  ```

  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

  curl -X GET "https://api.pinecone.io/admin/users" \
  	-H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
  	-H "accept: application/json" \
  	-H "X-Pinecone-Api-Version: 2026-04"
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "data": [
      {
        "id": "e2e92523-85dc-4142-b8c2-e681be8b78df",
        "email": "alice@example.com",
        "name": "Alice Example",
        "created_at": "2026-04-10T15:23:00Z",
        "updated_at": "2026-04-12T09:11:00Z"
      }
    ],
    "pagination": {
      "next": "eyJsYXN0X2lkIjoiZTJlOTI1MjMifQ=="
    }
  }
  ```
</ResponseExample>


# Resend an invite email
Source: https://docs.pinecone.io/reference/api/2026-04/admin/resend_invite

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml post /admin/invites/{invite_id}/resend
Resend the invite email and extend its expiration to 7 days from now; limited to 100 emails per hour per organization.


<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  const invite = await admin.invites.resend('YOUR_INVITE_ID');
  console.log(invite);
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "fmt"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      invite, err := adminClient.Invite.Resend(ctx, "YOUR_INVITE_ID")
      if err != nil {
          log.Fatalf("Failed to resend invite: %v", err)
      }
      fmt.Printf("Resent invite to %v (status: %v)\n", invite.Email, invite.Status)
  }
  ```

  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
  PINECONE_INVITE_ID="9c8e3528-b9c0-4358-84ce-84c28e91b566"

  curl -X POST "https://api.pinecone.io/admin/invites/$PINECONE_INVITE_ID/resend" \
  	-H "X-Pinecone-Api-Version: 2026-04" \
  	-H "Authorization: Bearer $PINECONE_ACCESS_TOKEN"
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "id": "9c8e3528-b9c0-4358-84ce-84c28e91b566",
    "email": "newhire@example.com",
    "status": "pending",
    "expires_at": "2026-05-28T20:14:00Z",
    "processed_at": null,
    "created_at": "2026-04-14T20:00:00Z"
  }
  ```
</ResponseExample>


# Rotate a service account's OAuth client secret
Source: https://docs.pinecone.io/reference/api/2026-04/admin/rotate_service_account_secret

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml post /admin/service-accounts/{service_account_id}/rotate-secret
Rotate a service account's OAuth client secret; the previous secret and its tokens are revoked within seconds and the new secret is returned only once.


<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  // The previous secret is invalidated, and the new one is returned only once
  const { serviceAccount, clientSecret } = await admin.serviceAccounts.rotateSecret(
    'YOUR_SERVICE_ACCOUNT_ID'
  );
  console.log(serviceAccount);
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "fmt"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      sa, err := adminClient.ServiceAccount.RotateSecret(ctx, "YOUR_SERVICE_ACCOUNT_ID")
      if err != nil {
          log.Fatalf("Failed to rotate service account secret: %v", err)
      }
      // ClientSecret is returned only once — store it securely and never log it
      fmt.Printf("Successfully rotated secret for service account: %v\n", sa.ServiceAccount.Id)
  }
  ```

  ```hcl Terraform theme={null}
  # Requires Terraform provider v4.0.0 or later
  # Change rotate_trigger to any new value to issue and store a new secret
  resource "pinecone_service_account" "ci_prod" {
    name           = "ci-prod"
    rotate_trigger = "2026-04-10"
  }
  ```

  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
  PINECONE_SERVICE_ACCOUNT_ID="f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c"

  curl -X POST "https://api.pinecone.io/admin/service-accounts/$PINECONE_SERVICE_ACCOUNT_ID/rotate-secret" \
  	-H "X-Pinecone-Api-Version: 2026-04" \
  	-H "Authorization: Bearer $PINECONE_ACCESS_TOKEN"
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "service_account": {
      "id": "f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
      "name": "My Service Account",
      "client_id": "l3Ow0CmFyc4jOONcwiKUCRqQKN0tiCAn",
      "created_at": "2026-04-10T15:23:00Z",
      "updated_at": "2026-04-10T15:23:00Z"
    },
    "client_secret": "8p-kkC23XOWvkCosKq-BOn3G74qp__rBcDMxc82iB4gfzRvuhSCRBKM7C5Q7TAzj"
  }
  ```
</ResponseExample>


# Update an API key
Source: https://docs.pinecone.io/reference/api/2026-04/admin/update_api_key

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml patch /admin/api-keys/{api_key_id}
Update an API key's name and roles.

<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  const apiKey = await admin.apiKeys.update('YOUR_API_KEY_ID', {
    name: 'New API key name',
    roles: ['ProjectEditor'],
  });
  console.log(apiKey);
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "fmt"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      name := "New API key name"
      roles := []string{"ProjectEditor"}
      apiKey, err := adminClient.APIKey.Update(ctx, "YOUR_API_KEY_ID", &pinecone.UpdateAPIKeyParams{
          Name:  &name,
          Roles: &roles,
      })
      if err != nil {
          log.Fatalf("Failed to update API key: %v", err)
      }
      fmt.Printf("Successfully updated API key: %v\n", apiKey.Name)
  }
  ```

  ```hcl Terraform theme={null}
  # Requires Terraform provider v4.0.0 or later
  # Change the name or roles on an existing resource, then run `terraform apply`
  resource "pinecone_api_key" "example" {
    name       = "New API key name"
    project_id = "YOUR_PROJECT_ID"
    roles      = ["ProjectEditor"]
  }
  ```

  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
  PINECONE_API_KEY_ID="YOUR_API_KEY_ID"

  curl -X PATCH "https://api.pinecone.io/admin/api-keys/$PINECONE_API_KEY_ID" \
  	-H "X-Pinecone-Api-Version: 2026-04" \
  	-H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
  	-d '{
  		"name": "New API key name",
  		"roles": ["ProjectEditor"]
  	}'
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "key": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "New API key name",
      "project_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "roles": [
        "ProjectEditor"
      ]
    },
    "value": "string"
  }
  ```
</ResponseExample>


# Update a project
Source: https://docs.pinecone.io/reference/api/2026-04/admin/update_project

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml patch /admin/projects/{project_id}
Update a project's name, maximum number of Pods, or customer-managed encryption key (CMEK).


<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  const project = await admin.projects.update('YOUR_PROJECT_ID', {
    name: 'updated-example-project',
  });
  console.log(project);
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "fmt"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      name := "updated-example-project"
      project, err := adminClient.Project.Update(ctx, "YOUR_PROJECT_ID", &pinecone.UpdateProjectParams{
          Name: &name,
      })
      if err != nil {
          log.Fatalf("Failed to update project: %v", err)
      }
      fmt.Printf("Successfully updated project: %v\n", project.Name)
  }
  ```

  ```hcl Terraform theme={null}
  # Requires Terraform provider v4.0.0 or later
  # Change the name on an existing resource, then run `terraform apply`
  resource "pinecone_project" "example" {
    name = "updated-example-project"
  }
  ```

  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
  PROJECT_ID="YOUR_PROJECT_ID"

  curl -X PATCH "https://api.pinecone.io/admin/projects/$PROJECT_ID" \
    -H "accept: application/json" \
    -H "Content-Type: application/json" \
    -H "X-Pinecone-Api-Version: 2026-04" \
    -d '{
      "name": "updated-example-project"
      }'
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "updated-example-project",
    "max_pods": 0,
    "force_encryption_with_cmek": false,
    "organization_id": "string",
    "created_at": "2025-03-17T00:42:31.912Z"
  }
  ```
</ResponseExample>


# Update a service account
Source: https://docs.pinecone.io/reference/api/2026-04/admin/update_service_account

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml patch /admin/service-accounts/{service_account_id}
Update a service account's name; role bindings are managed through the role-binding endpoints.


<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  const serviceAccount = await admin.serviceAccounts.update('YOUR_SERVICE_ACCOUNT_ID', {
    name: 'ci-prod-renamed',
  });
  console.log(serviceAccount);
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "fmt"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      name := "ci-prod-renamed"
      sa, err := adminClient.ServiceAccount.Update(ctx, "YOUR_SERVICE_ACCOUNT_ID", &pinecone.UpdateServiceAccountParams{
          Name: &name,
      })
      if err != nil {
          log.Fatalf("Failed to update service account: %v", err)
      }
      fmt.Printf("Successfully updated service account: %v\n", sa.Name)
  }
  ```

  ```hcl Terraform theme={null}
  # Requires Terraform provider v4.0.0 or later
  # Change the name on an existing resource, then run `terraform apply`
  resource "pinecone_service_account" "ci_prod" {
    name = "ci-prod-renamed"
  }
  ```

  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
  PINECONE_SERVICE_ACCOUNT_ID="YOUR_SERVICE_ACCOUNT_ID"

  curl -X PATCH "https://api.pinecone.io/admin/service-accounts/$PINECONE_SERVICE_ACCOUNT_ID" \
  	-H "X-Pinecone-Api-Version: 2026-04" \
  	-H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
  	-d '{
  		"name": "ci-prod-renamed"
  	}'
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "id": "f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
    "name": "ci-prod-renamed",
    "client_id": "l3Ow0CmFyc4jOONcwiKUCRqQKN0tiCAn",
    "created_at": "2026-04-10T15:23:00Z",
    "updated_at": "2026-04-12T09:11:00Z"
  }
  ```
</ResponseExample>


# Create a backup of an index
Source: https://docs.pinecone.io/reference/api/2026-04/control-plane/create_backup

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_control_2026-04.oas.yaml post /indexes/{index_name}/backups
Create a backup of an index.


<RequestExample>
  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  INDEX_NAME="docs-example"

  curl "https://api.pinecone.io/indexes/$INDEX_NAME/backups" \
      -H "Api-Key: $PINECONE_API_KEY" \
      -H 'accept: application/json' \
      -H 'Content-Type: application/json' \
      -H "X-Pinecone-Api-Version: 2026-04" \
      -d '{
        "name": "example-backup", 
        "description": "Monthly backup of production index"
        }'
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "backup_id":"8c85e612-ed1c-4f97-9f8c-8194e07bcf71",
    "source_index_id":"f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74",
    "source_index_name":"docs-example",
    "tags":{},
    "name":"example-backup",
    "description":"Monthly backup of production index",
    "status":"Ready",
    "cloud":"aws",
    "region":"us-east-1",
    "dimension":1024,
    "record_count":96,
    "namespace_count":3,
    "size_bytes":1069169,
    "created_at":"2025-05-14T16:37:25.625540Z"
    }
  ```
</ResponseExample>


# Create backup schedule
Source: https://docs.pinecone.io/reference/api/2026-04/control-plane/create_backup_schedule

POST https://api.pinecone.io/indexes/{index_name}/backup-schedules
Create a recurring backup schedule for a Pinecone serverless index using the API, including daily, weekly, or monthly frequency and retention policy.

<Note>
  This endpoint requires `X-Pinecone-API-Version: unstable`.
</Note>

Create a recurring backup schedule for an index. Backups are created automatically based on the specified frequency and expired according to the retention policy. Each index supports one active schedule at a time.

### Path parameters

<ParamField type="string">
  The name of the index to create a backup schedule for.
</ParamField>

### Body parameters

<ParamField type="string">
  A human-readable name for the backup schedule. Backups created by the schedule are automatically named `{name}-{ISO8601_timestamp}`.
</ParamField>

<ParamField type="object">
  The schedule configuration.

  <Expandable title="schedule properties">
    <ParamField type="string">
      The type of schedule. Currently only `time-based` is supported.
    </ParamField>

    <ParamField type="string">
      How often backups are created. One of `daily`, `weekly`, or `monthly`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  The retention policy for backups created by this schedule.

  <Expandable title="retention properties">
    <ParamField type="integer">
      The number of days after which backups created by this schedule are automatically deleted.
    </ParamField>
  </Expandable>
</ParamField>

### Error responses

| Status | Description                                                                    |
| :----- | :----------------------------------------------------------------------------- |
| 403    | Scheduled backups are not available for your plan.                             |
| 404    | Index not found.                                                               |
| 409    | This index already has an enabled backup schedule. Disable or delete it first. |

<RequestExample>
  ```bash curl theme={null}
  curl -sS -X POST "https://api.pinecone.io/indexes/${INDEX_NAME}/backup-schedules" \
    -H "api-key: ${PINECONE_API_KEY}" \
    -H "X-Pinecone-API-Version: unstable" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "my-nightly-backup",
      "schedule": {
        "type": "time-based",
        "frequency": "daily"
      },
      "retention": {
        "expire_after_days": 7
      }
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "schedule_id": "c688ed12-5a39-4254-9518-bd394b7f4886",
    "name": "my-nightly-backup",
    "index_id": "d40265e4-a492-402b-9cf1-973b4908b7a0",
    "project_id": "cc95c601-bf08-4973-9a1d-a65a1b528759",
    "schedule_type": "time-based",
    "frequency": "daily",
    "retention_expire_after_days": 7,
    "enabled": true,
    "next_scheduled_run": "2026-04-24T06:00:00+00:00",
    "created_at": "2026-04-23T16:36:51.267528+00:00"
  }
  ```
</ResponseExample>


# Create a collection
Source: https://docs.pinecone.io/reference/api/2026-04/control-plane/create_collection

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_control_2026-04.oas.yaml post /collections
Create a Pinecone collection.
  
Serverless indexes do not support collections.


<RequestExample>
  ```shell curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"

  curl -s "https://api.pinecone.io/collections" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2026-04" \
    -d '{
          "name": "example-collection",
          "source": "docs-example"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
      "name": "example-collection",
      "status": "Initializing",
      "environment": "us-east-1-aws",
      "dimension": 1536
  }
  ```
</ResponseExample>


# Create an index from a backup
Source: https://docs.pinecone.io/reference/api/2026-04/control-plane/create_index_from_backup

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_control_2026-04.oas.yaml post /backups/{backup_id}/create-index
Create an index from a backup. For serverless backups, you can optionally set `read_capacity` so the restored index is created with dedicated read nodes (DRN) instead of defaulting to on-demand capacity.

<RequestExample>
  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  BACKUP_ID="a65ff585-d987-4da5-a622-72e19a6ed5f4"

  curl "https://api.pinecone.io/backups/$BACKUP_ID/create-index" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2026-04" \
    -H 'Content-Type: application/json' \
    -d '{
          "name": "restored-index",
          "tags": {
            "tag0": "val0",
            "tag1": "val1"
          },
          "deletion_protection": "enabled"
        }'
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
      "restore_job_id":"e9ba8ff8-7948-4cfa-ba43-34227f6d30d4",
      "index_id":"025117b3-e683-423c-b2d1-6d30fbe5027f"
  }
  ```
</ResponseExample>


# Delete a backup
Source: https://docs.pinecone.io/reference/api/2026-04/control-plane/delete_backup

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_control_2026-04.oas.yaml delete /backups/{backup_id}
Delete a backup.

<RequestExample>
  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  BACKUP_ID="9947520e-d5a1-4418-a78d-9f464c9969da"

  curl -X DELETE "https://api.pinecone.io/backups/$BACKUP_ID" \
      -H "Api-Key: $PINECONE_API_KEY" \
      -H "X-Pinecone-Api-Version: 2026-04"
  ```
</RequestExample>

<ResponseExample />


# Delete backup schedule
Source: https://docs.pinecone.io/reference/api/2026-04/control-plane/delete_backup_schedule

DELETE https://api.pinecone.io/backup-schedules/{schedule_id}
Delete a backup schedule for a Pinecone serverless index using the API by schedule ID, while preserving all previously created backup snapshots.

<Note>
  This endpoint requires `X-Pinecone-API-Version: unstable`.
</Note>

Delete a backup schedule. This does **not** delete any backups that were previously created by the schedule.

### Path parameters

<ParamField type="string">
  The ID of the backup schedule to delete.
</ParamField>

<RequestExample>
  ```bash curl theme={null}
  curl -sS -o /dev/null -w "%{http_code}\n" -X DELETE \
    "https://api.pinecone.io/backup-schedules/${SCHEDULE_ID}" \
    -H "api-key: ${PINECONE_API_KEY}" \
    -H "X-Pinecone-API-Version: unstable"
  ```
</RequestExample>

<ResponseExample>
  ```text curl theme={null}
  204
  ```
</ResponseExample>


# Delete a collection
Source: https://docs.pinecone.io/reference/api/2026-04/control-plane/delete_collection

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_control_2026-04.oas.yaml delete /collections/{collection_name}
Delete an existing collection.
Serverless indexes do not support collections.


<RequestExample>
  ```shell curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"

  curl -i -X DELETE "https://api.pinecone.io/collections/example-collection" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2026-04"
  ```
</RequestExample>

<ResponseExample />


# Describe a backup
Source: https://docs.pinecone.io/reference/api/2026-04/control-plane/describe_backup

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_control_2026-04.oas.yaml get /backups/{backup_id}
Get a description of a backup.

<RequestExample>
  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  BACKUP_ID="8c85e612-ed1c-4f97-9f8c-8194e07bcf71"

  curl -X GET "https://api.pinecone.io/backups/$BACKUP_ID" \
      -H "Api-Key: $PINECONE_API_KEY" \
      -H "X-Pinecone-Api-Version: 2026-04" \
      -H "accept: application/json"
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "backup_id":"8c85e612-ed1c-4f97-9f8c-8194e07bcf71",
    "source_index_id":"f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74",
    "source_index_name":"docs-example",
    "tags":{},
    "name":"example-backup",
    "description":"Monthly backup of production index",
    "status":"Ready",
    "cloud":"aws",
    "region":"us-east-1",
    "dimension":1024,
    "record_count":98,
    "namespace_count":3,
    "size_bytes":1069169,
    "created_at":"2025-03-11T18:29:50.549505Z"
  }
  ```
</ResponseExample>


# Describe backup schedule
Source: https://docs.pinecone.io/reference/api/2026-04/control-plane/describe_backup_schedule

GET https://api.pinecone.io/backup-schedules/{schedule_id}
Retrieve details for a Pinecone backup schedule by schedule ID, including frequency, retention days, next scheduled run, and enabled status.

<Note>
  This endpoint requires `X-Pinecone-API-Version: unstable`.
</Note>

Get the details of a specific backup schedule by its ID.

### Path parameters

<ParamField type="string">
  The ID of the backup schedule.
</ParamField>

<RequestExample>
  ```bash curl theme={null}
  curl -sS "https://api.pinecone.io/backup-schedules/${SCHEDULE_ID}" \
    -H "api-key: ${PINECONE_API_KEY}" \
    -H "X-Pinecone-API-Version: unstable"
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "schedule_id": "c688ed12-5a39-4254-9518-bd394b7f4886",
    "name": "my-nightly-backup",
    "index_id": "d40265e4-a492-402b-9cf1-973b4908b7a0",
    "project_id": "cc95c601-bf08-4973-9a1d-a65a1b528759",
    "schedule_type": "time-based",
    "frequency": "daily",
    "retention_expire_after_days": 7,
    "enabled": true,
    "next_scheduled_run": "2026-04-24T06:00:00+00:00",
    "created_at": "2026-04-23T16:36:51.267528+00:00"
  }
  ```
</ResponseExample>


# Describe a collection
Source: https://docs.pinecone.io/reference/api/2026-04/control-plane/describe_collection

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_control_2026-04.oas.yaml get /collections/{collection_name}
Get a description of a collection.
Serverless indexes do not support collections.


<RequestExample>
  ```shell curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"

  curl -i -X GET "https://api.pinecone.io/collections/tiny-collection" \
      -H "Api-Key: $PINECONE_API_KEY" \
      -H "X-Pinecone-Api-Version: 2026-04"
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
      "name": "example-collection",
      "status": "Ready",
      "environment": "us-east-1-aws",
      "size": 3075398,
      "vector_count": 99,
      "dimension": 1536
  }
  ```
</ResponseExample>


# Describe a restore job
Source: https://docs.pinecone.io/reference/api/2026-04/control-plane/describe_restore_job

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_control_2026-04.oas.yaml get /restore-jobs/{job_id}
Get a description of a restore job.

<RequestExample>
  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  JOB_ID="9857add2-99d4-4399-870e-aa7f15d8d326"

  curl "https://api.pinecone.io/restore-jobs/$JOB_ID" \
      -H "X-Pinecone-Api-Version: 2026-04" \
      -H "Api-Key: $PINECONE_API_KEY" \
      -H 'accept: application/json'
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "restore_job_id": "9857add2-99d4-4399-870e-aa7f15d8d326",
    "backup_id": "94a63aeb-efae-4f7a-b059-75d32c27ca57",
    "target_index_name": "restored-index",
    "target_index_id": "0d8aed24-adf8-4b77-8e10-fd674309dc85",
    "status": "Completed",
    "created_at": "2025-04-25T18:14:05.227526Z",
    "completed_at": "2025-04-25T18:14:11.074618Z",
    "percent_complete": 100
  }
  ```
</ResponseExample>


# List backup schedule history
Source: https://docs.pinecone.io/reference/api/2026-04/control-plane/list_backup_schedule_history

GET https://api.pinecone.io/backup-schedules/{schedule_id}/history
List execution history for a Pinecone backup schedule, including scheduled runs, completed backups, statuses, and cursor-based pagination support.

<Note>
  This endpoint requires `X-Pinecone-API-Version: unstable`.
</Note>

List backups created by a specific schedule. When a backup's `status` is `Scheduled`, the `scheduled_execution_at` field indicates the planned run time. Supports pagination.

### Path parameters

<ParamField type="string">
  The ID of the backup schedule.
</ParamField>

### Query parameters

<ParamField type="integer">
  The maximum number of results to return.
</ParamField>

<ParamField type="string">
  A token for fetching the next page of results.
</ParamField>

<RequestExample>
  ```bash curl theme={null}
  curl -sS "https://api.pinecone.io/backup-schedules/${SCHEDULE_ID}/history" \
    -H "api-key: ${PINECONE_API_KEY}" \
    -H "X-Pinecone-API-Version: unstable"
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "data": [
      {
        "backup_id": "16098c2f-f9ff-4db3-b8b2-4b02d119cd53",
        "source_index_id": "d40265e4-a492-402b-9cf1-973b4908b7a0",
        "source_index_name": "my-index",
        "tags": {},
        "name": "my-nightly-backup-20260424T060000Z",
        "description": null,
        "status": "Scheduled",
        "scheduled_execution_at": "2026-04-24T06:00:00.244035Z",
        "cloud": "aws",
        "region": "us-east-1",
        "dimension": 2,
        "schema": null,
        "record_count": null,
        "namespace_count": null,
        "size_bytes": null,
        "created_at": "2026-04-23T16:36:51.511526Z"
      }
    ],
    "pagination": null
  }
  ```
</ResponseExample>


# List backup schedules
Source: https://docs.pinecone.io/reference/api/2026-04/control-plane/list_backup_schedules

GET https://api.pinecone.io/indexes/{index_name}/backup-schedules
List all backup schedules configured for a Pinecone serverless index, including schedule IDs, frequency, retention, and next scheduled run times.

<Note>
  This endpoint requires `X-Pinecone-API-Version: unstable`.
</Note>

List all backup schedules configured for a specific index.

### Path parameters

<ParamField type="string">
  The name of the index to list backup schedules for.
</ParamField>

<RequestExample>
  ```bash curl theme={null}
  curl -sS "https://api.pinecone.io/indexes/${INDEX_NAME}/backup-schedules" \
    -H "api-key: ${PINECONE_API_KEY}" \
    -H "X-Pinecone-API-Version: unstable"
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "data": [
      {
        "schedule_id": "c688ed12-5a39-4254-9518-bd394b7f4886",
        "name": "my-nightly-backup",
        "index_id": "d40265e4-a492-402b-9cf1-973b4908b7a0",
        "project_id": "cc95c601-bf08-4973-9a1d-a65a1b528759",
        "schedule_type": "time-based",
        "frequency": "daily",
        "retention_expire_after_days": 7,
        "enabled": true,
        "next_scheduled_run": "2026-04-24T06:00:00+00:00",
        "created_at": "2026-04-23T16:36:51.267528+00:00"
      }
    ],
    "pagination": null
  }
  ```
</ResponseExample>


# List collections
Source: https://docs.pinecone.io/reference/api/2026-04/control-plane/list_collections

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_control_2026-04.oas.yaml get /collections
List all collections in a project.
Serverless indexes do not support collections.


<RequestExample>
  ```shell curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"

  curl -i -X GET "https://api.pinecone.io/collections" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2026-04"
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
      "collections": [
          {
              "name": "example-collection1",
              "status": "Ready",
              "environment": "us-east-1-aws",
              "size": 3081918,
              "vector_count": 99,
              "dimension": 3
          },
          {
              "name": "example-collection1",
              "status": "Ready",
              "environment": "us-east-1-aws",
              "size": 160087040000000,
              "vector_count": 10000000,
              "dimension": 1536
          }
      ]
  }
  ```
</ResponseExample>


# List backups for an index
Source: https://docs.pinecone.io/reference/api/2026-04/control-plane/list_index_backups

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_control_2026-04.oas.yaml get /indexes/{index_name}/backups
When `include_deleted` is false (or omitted), `index_name` must resolve to an active index in the project. If no active index by that name exists—including the case where only deleted indexes have used the name—the API returns **404**, not an empty list.
When `include_deleted` is true, the API returns backups from every index in the project that has ever used this name (active and deleted). The `source_index_deleted_at` field is present only when the backup is from a deleted index. **404** is returned only when no index by that name has ever existed in the project (active or deleted).

<RequestExample>
  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  INDEX_NAME="docs-example"

  curl -X GET "https://api.pinecone.io/indexes/$INDEX_NAME/backups" \
      -H "Api-Key: $PINECONE_API_KEY" \
      -H "X-Pinecone-Api-Version: 2026-04" \
      -H "accept: application/json"
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "data":
    [
      {
        "backup_id":"9947520e-d5a1-4418-a78d-9f464c9969da",
        "source_index_id":"8433941a-dae7-43b5-ac2c-d3dab4a56b2b",
        "source_index_name":"docs-example",
        "tags":{},
        "name":"example-backup",
        "description":"Monthly backup of production index",
        "status":"Pending",
        "cloud":"aws",
        "region":"us-east-1",
        "dimension":1024,
        "record_count":98,
        "namespace_count":3,
        "size_bytes":1069169,
        "created_at":"2025-03-11T18:29:50.549505Z"
        }
      ],
    "pagination":null
  }
  ```
</ResponseExample>


# List backups for all indexes in a project
Source: https://docs.pinecone.io/reference/api/2026-04/control-plane/list_project_backups

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_control_2026-04.oas.yaml get /backups
List all backups for a project.

<RequestExample>
  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"

  curl -X GET "https://api.pinecone.io/backups" \
      -H "Api-Key: $PINECONE_API_KEY" \
      -H "X-Pinecone-Api-Version: 2026-04" \
      -H "accept: application/json"
  ```
</RequestExample>

<ResponseExample>
  ```json curl  theme={null}
  {
    "data": [
      {
        "backup_id": "e12269b0-a29b-4af0-9729-c7771dec03e3",
        "source_index_id": "bcb5b3c9-903e-4cb6-8b37-a6072aeb874f",
        "source_index_name": "docs-example",
        "tags": null,
        "name": "example-backup",
        "description": null,
        "status": "Ready",
        "cloud": "aws",
        "region": "us-east-1",
        "dimension": 0,
        "record_count": 96,
        "namespace_count": 1,
        "size_bytes": 86393,
        "created_at": "2025-05-14T17:00:45.803146Z"
      },
      {
        "backup_id": "d686451d-1ede-4004-9f72-7d22cc799b6e",
        "source_index_id": "b49f27d1-1bf3-49c6-82b5-4ae46f00f0e6",
        "source_index_name": "docs-example2",
        "tags": null,
        "name": "example-backup2",
        "description": null,
        "status": "Ready",
        "cloud": "aws",
        "region": "us-east-1",
        "dimension": 1024,
        "record_count": 50,
        "namespace_count": 1,
        "size_bytes": 545171,
        "created_at": "2025-05-14T17:00:34.814371Z"
      },
      {
        "backup_id": "8c85e612-ed1c-4f97-9f8c-8194e07bcf71",
        "source_index_id": "f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74",
        "source_index_name": "docs-example3",
        "tags": {},
        "name": "example-backup3",
        "description": "Monthly backup of production index",
        "status": "Ready",
        "cloud": "aws",
        "region": "us-east-1",
        "dimension": 1024,
        "record_count": 98,
        "namespace_count": 3,
        "size_bytes": 1069169,
        "created_at": "2025-05-14T16:37:25.625540Z"
      }
    ],
    "pagination": null
  }
  ```
</ResponseExample>


# List restore jobs
Source: https://docs.pinecone.io/reference/api/2026-04/control-plane/list_restore_jobs

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_control_2026-04.oas.yaml get /restore-jobs
List all restore jobs for a project.

<RequestExample>
  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"

  curl "https://api.pinecone.io/restore-jobs" \
  	-H "X-Pinecone-Api-Version: 2026-04" \
  	-H "Api-Key: $PINECONE_API_KEY"
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "data": [
      {
        "restore_job_id": "9857add2-99d4-4399-870e-aa7f15d8d326",
        "backup_id": "94a63aeb-efae-4f7a-b059-75d32c27ca57",
        "target_index_name": "restored-index",
        "target_index_id": "0d8aed24-adf8-4b77-8e10-fd674309dc85",
        "status": "Completed",
        "created_at": "2025-04-25T18:14:05.227526Z",
        "completed_at": "2025-04-25T18:14:11.074618Z",
        "percent_complete": 100
      },
      {
        "restore_job_id": "69acc1d0-9105-4fcb-b1db-ebf97b285c5e",
        "backup_id": "8c85e612-ed1c-4f97-9f8c-8194e07bcf71",
        "target_index_name": "restored-index2",
        "target_index_id": "e6c0387f-33db-4227-9e91-32181106e56b",
        "status": "Completed",
        "created_at": "2025-05-14T17:25:59.378989Z",
        "completed_at": "2025-05-14T17:26:23.997284Z",
        "percent_complete": 100
      }
    ],
    "pagination": null
  }
  ```
</ResponseExample>


# Update backup schedule
Source: https://docs.pinecone.io/reference/api/2026-04/control-plane/update_backup_schedule

PATCH https://api.pinecone.io/backup-schedules/{schedule_id}
Update a Pinecone backup schedule using the API, including pausing with enabled, changing frequency, and adjusting the retention expire_after_days.

<Note>
  This endpoint requires `X-Pinecone-API-Version: unstable`.
</Note>

Update a backup schedule. Send only the fields you want to change. All body fields are optional.

### Path parameters

<ParamField type="string">
  The ID of the backup schedule to update.
</ParamField>

### Body parameters

<ParamField type="boolean">
  Whether the schedule is enabled. Set to `false` to pause the schedule without deleting it.
</ParamField>

<ParamField type="string">
  How often backups are created. One of `daily`, `weekly`, or `monthly`.
</ParamField>

<ParamField type="object">
  The retention policy for backups created by this schedule.

  <Expandable title="retention properties">
    <ParamField type="integer">
      The number of days after which backups created by this schedule are automatically deleted.
    </ParamField>
  </Expandable>
</ParamField>

<RequestExample>
  ```bash curl theme={null}
  curl -sS -X PATCH "https://api.pinecone.io/backup-schedules/${SCHEDULE_ID}" \
    -H "api-key: ${PINECONE_API_KEY}" \
    -H "X-Pinecone-API-Version: unstable" \
    -H "Content-Type: application/json" \
    -d '{
      "enabled": false,
      "frequency": "weekly",
      "retention": { "expire_after_days": 14 }
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "schedule_id": "c688ed12-5a39-4254-9518-bd394b7f4886",
    "name": "my-nightly-backup",
    "index_id": "d40265e4-a492-402b-9cf1-973b4908b7a0",
    "project_id": "cc95c601-bf08-4973-9a1d-a65a1b528759",
    "schedule_type": "time-based",
    "frequency": "weekly",
    "retention_expire_after_days": 14,
    "enabled": false,
    "next_scheduled_run": "2026-04-24T06:00:00+00:00",
    "created_at": "2026-04-23T16:36:51.267528+00:00"
  }
  ```
</ResponseExample>


# Cancel an import
Source: https://docs.pinecone.io/reference/api/2026-04/data-plane/cancel_import

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_data_2026-04.oas.yaml delete /bulk/imports/{id}
Cancel an import operation if it is not yet finished. It has no effect if the operation is already finished.

For guidance and examples, see [Import data](https://docs.pinecone.io/guides/index-data/import-data).

<Note>
  This feature is in [public preview](/release-notes/feature-availability) and available only on [Standard and Enterprise plans](https://www.pinecone.io/pricing/).
</Note>

<RequestExample>
  ```bash curl theme={null}
  # To get the unique host for an index,
  # see https://docs.pinecone.io/guides/manage-data/target-an-index
  PINECONE_API_KEY="YOUR_API_KEY"
  INDEX_HOST="INDEX_HOST"

  curl -X DELETE "https://$INDEX_HOST/bulk/imports/101" \
    -H 'Api-Key: $PINECONE_API_KEY' \
    -H "X-Pinecone-Api-Version: 2026-04"
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {}
  ```
</ResponseExample>


# Delete records
Source: https://docs.pinecone.io/reference/api/2026-04/data-plane/delete

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_data_2026-04.oas.yaml post /vectors/delete
Delete records by id or by metadata from a single namespace.

For guidance and examples, see [Delete data](https://docs.pinecone.io/guides/manage-data/delete-data).

<RequestExample>
  ```shell curl theme={null}
  # To get the unique host for an index,
  # see https://docs.pinecone.io/guides/manage-data/target-an-index
  PINECONE_API_KEY="YOUR_API_KEY"
  INDEX_HOST="INDEX_HOST"

  curl "https://$INDEX_HOST/vectors/delete" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "Content-Type: application/json" \
    -H "X-Pinecone-Api-Version: 2026-04" \
    -d '{
      "ids": [
        "id-1", 
        "id-2"
      ],
      "namespace": "example-namespace"
    }
  '
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {}
  ```
</ResponseExample>


# Describe an import
Source: https://docs.pinecone.io/reference/api/2026-04/data-plane/describe_import

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_data_2026-04.oas.yaml get /bulk/imports/{id}
Return details of a specific import operation.

For guidance and examples, see [Import data](https://docs.pinecone.io/guides/index-data/import-data).

<Note>
  This feature is in [public preview](/release-notes/feature-availability) and available only on [Standard and Enterprise plans](https://www.pinecone.io/pricing/).
</Note>

<RequestExample>
  ```bash curl theme={null}
  # To get the unique host for an index, 
  # see https://docs.pinecone.io/guides/manage-data/target-an-index
  PINECONE_API_KEY="YOUR_API_KEY"
  INDEX_HOST="INDEX_HOST"

  curl -X GET "https://$INDEX_HOST/bulk/imports/101" \
    -H 'Api-Key: $PINECONE_API_KEY' \
    -H 'X-Pinecone-Api-Version: 2026-04'
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "id": "101",
    "uri": "s3://BUCKET_NAME/PATH/TO/DIR",
    "status": "Pending",
    "created_at": "2024-08-19T20:49:00.754Z",
    "finished_at": "2024-08-19T20:49:00.754Z",
    "percent_complete": 42.2,
    "records_imported": 1000000
  }
  ```
</ResponseExample>


# List record IDs
Source: https://docs.pinecone.io/reference/api/2026-04/data-plane/list

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_data_2026-04.oas.yaml get /vectors/list
List the IDs of records in a single namespace of a serverless index. An optional prefix can be passed to limit the results to IDs with a common prefix.

Returns up to 100 IDs at a time by default in sorted order (bitwise "C" collation). If the `limit` parameter is set, `list` returns up to that number of IDs instead. Whenever there are additional IDs to return, the response also includes a `pagination_token` that you can use to get the next batch of IDs. When the response does not include a `pagination_token`, there are no more IDs to return.

For guidance and examples, see [List record IDs](https://docs.pinecone.io/guides/manage-data/list-record-ids).

**Note:** `list` is supported only for serverless indexes.

<RequestExample>
  ```shell curl theme={null}
  # To get the unique host for an index,
  # see https://docs.pinecone.io/guides/manage-data/target-an-index
  PINECONE_API_KEY="YOUR_API_KEY"
  INDEX_HOST="INDEX_HOST"

  curl -X GET "https://$INDEX_HOST/vectors/list?namespace=example-namespace&prefix=doc1#&limit=3" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2026-04"
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "vectors": [
      { "id": "doc1#chunk1" },
      { "id": "doc1#chunk2" },
      { "id": "doc1#chunk3" }
    ],
    "pagination": {
      "next": "c2Vjb25kY2FsbA=="
    },
    "namespace": "example-namespace",
    "usage": {
      "readUnits": 1
    }
  }
  ```
</ResponseExample>


# List imports
Source: https://docs.pinecone.io/reference/api/2026-04/data-plane/list_imports

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_data_2026-04.oas.yaml get /bulk/imports
List all recent and ongoing import operations.

By default, `list_imports` returns up to 100 imports per page. If the `limit` parameter is set, `list` returns up to that number of imports instead. Whenever there are additional IDs to return, the response also includes a `pagination_token` that you can use to get the next batch of imports. When the response does not include a `pagination_token`, there are no more imports to return.

For guidance and examples, see [Import data](https://docs.pinecone.io/guides/index-data/import-data).

<Note>
  This feature is in [public preview](/release-notes/feature-availability) and available only on [Standard and Enterprise plans](https://www.pinecone.io/pricing/).
</Note>

<RequestExample>
  ```bash curl theme={null}
  # To get the unique host for an index,
  # see https://docs.pinecone.io/guides/manage-data/target-an-index
  PINECONE_API_KEY="YOUR_API_KEY"
  INDEX_HOST="INDEX_HOST"

  curl -X GET "https://$INDEX_HOST/bulk/imports?paginationToken==Tm90aGluZyB0byBzZWUgaGVyZQo" \
    -H 'Api-Key: $PINECONE_API_KEY' \
    -H 'X-Pinecone-Api-Version: 2026-04'
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "data": [
      {
        "id": "1",
        "uri": "s3://BUCKET_NAME/PATH/TO/DIR",
        "status": "Pending",
        "started_at": "2024-08-19T20:49:00.754Z",
        "finished_at": "2024-08-19T20:49:00.754Z",
        "percent_complete": 42.2,
        "records_imported": 1000000
      }
    ],
    "pagination": {
      "next": "Tm90aGluZyB0byBzZWUgaGVyZQo="
    }
  }
  ```
</ResponseExample>


# Search with a vector
Source: https://docs.pinecone.io/reference/api/2026-04/data-plane/query

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_data_2026-04.oas.yaml post /query
Search a namespace using a query vector. It retrieves the ids of the most similar items in a namespace, along with their similarity scores.

For guidance, examples, and limits, see [Search](https://docs.pinecone.io/guides/search/search-overview).

<RequestExample>
  ```shell curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  INDEX_HOST="INDEX_HOST"

  curl "https://$INDEX_HOST/query" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "Content-Type: application/json" \
    -H "X-Pinecone-Api-Version: 2026-04" \
    -d '{
      "namespace": "example-namespace",
      "vector": [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3],
      "filter": {"genre": {"$eq": "documentary"}},
      "topK": 3,
      "includeValues": true
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "matches":[
      {
        "id": "vec3",
        "score": 0,
        "values": [0.3,0.3,0.3,0.3,0.3,0.3,0.3,0.3]
      },
      {
        "id": "vec2",
        "score": 0.0800000429,
        "values": [0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2]
      },
      {
        "id": "vec4",
        "score": 0.0799999237,
        "values": [0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4]
      }
    ],
    "namespace": "example-namespace",
    "usage": {"read_units": 6}
  }
  ```
</ResponseExample>


# Search with text
Source: https://docs.pinecone.io/reference/api/2026-04/data-plane/search_records

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_data_2026-04.oas.yaml post /records/namespaces/{namespace}/search
Search a namespace with a query text, query vector, or record ID and return the most similar records, along with their similarity scores. Optionally, rerank the initial results based on their relevance to the query. 

Searching with text is supported only for indexes with [integrated embedding](https://docs.pinecone.io/guides/index-data/indexing-overview#vector-embedding). Searching with a query vector or record ID is supported for all indexes. 

For guidance and examples, see [Search](https://docs.pinecone.io/guides/search/search-overview).

<RequestExample>
  ```shell curl theme={null}
  INDEX_HOST="INDEX_HOST"
  NAMESPACE="YOUR_NAMESPACE"
  PINECONE_API_KEY="YOUR_API_KEY"

  # Search with a query text and rerank the results
  # Supported only for indexes with integrated embedding
  curl "https://$INDEX_HOST/records/namespaces/$NAMESPACE/search" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2026-04" \
    -d '{
          "query": {
              "inputs": {"text": "Disease prevention"},
              "top_k": 4,
          },
          "fields": ["category", "chunk_text"]
          "rerank": {
              "model": "bge-reranker-v2-m3",
              "top_n": 2,
              "rank_fields": ["chunk_text"] # Specified field must also be included in 'fields'
          }
       }'

  # Search with a query vector and rerank the results
  curl "https://$INDEX_HOST/records/namespaces/$NAMESPACE/search" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2026-04" \
    -d '{
          "query": {
              "vector": {
                  "values": [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3]
              },
              "top_k": 4,
          },
          "fields": ["category", "chunk_text"]
          "rerank": {
              "query": "Disease prevention",
              "model": "bge-reranker-v2-m3",
              "top_n": 2,
              "rank_fields": ["chunk_text"] # Specified field must also be included in 'fields'
          }
       }'

  # Search with a record ID and rerank the results
  # Supported only for indexes with integrated embedding
  curl "https://$INDEX_HOST/records/namespaces/$NAMESPACE/search" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2026-04" \
    -d '{
          "query": {
              "id": "rec1",
              "top_k": 4,
          },
          "fields": ["category", "chunk_text"]
          "rerank": {
              "query": "Disease prevention",
              "model": "bge-reranker-v2-m3",
              "top_n": 2,
              "rank_fields": ["chunk_text"]
          }
       }'
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
      "result": {
          "hits": [
              {
                  "_id": "rec3",
                  "_score": 0.004433765076100826,
                  "fields": {
                      "category": "immune system",
                      "chunk_text": "Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases."
                  }
              },
              {
                  "_id": "rec4",
                  "_score": 0.0029121784027665854,
                  "fields": {
                      "category": "endocrine system",
                      "chunk_text": "The high fiber content in apples can also help regulate blood sugar levels, making them a favorable snack for people with diabetes."
                  }
              }
          ]
      },
      "usage": {
          "embed_total_tokens": 8,
          "read_units": 6,
          "rerank_units": 1
      }
  }
  ```
</ResponseExample>


# Start import
Source: https://docs.pinecone.io/reference/api/2026-04/data-plane/start_import

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_data_2026-04.oas.yaml post /bulk/imports
Start an asynchronous import of vectors from object storage into an index.

For guidance and examples, see [Import data](https://docs.pinecone.io/guides/index-data/import-data).

<Note>
  This feature is in [public preview](/release-notes/feature-availability) and available only on [Standard and Enterprise plans](https://www.pinecone.io/pricing/).
</Note>

<RequestExample>
  ```bash curl theme={null}
  # To get the unique host for an index,
  # see https://docs.pinecone.io/guides/manage-data/target-an-index
  PINECONE_API_KEY="YOUR_API_KEY"
  INDEX_HOST="INDEX_HOST"

  curl "https://$INDEX_HOST/bulk/imports" \
    -H 'Api-Key: $PINECONE_API_KEY' \
    -H 'Content-Type: application/json' \
    -H 'X-Pinecone-Api-Version: 2026-04' \
    -d '{
          "integrationId": "a12b3d4c-47d2-492c-a97a-dd98c8dbefde",
          "uri": "s3://BUCKET_NAME/PATH/TO/DIR",
          "errorMode": {
              "onError": "continue"
              }
          }'
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
     "id": "101"
  }
  ```
</ResponseExample>


# Update a record
Source: https://docs.pinecone.io/reference/api/2026-04/data-plane/update

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_data_2026-04.oas.yaml post /vectors/update
Update records by ID or by metadata in a namespace. Updating by ID changes the vector and/or metadata of a single record. Updating by metadata changes metadata across multiple records using a metadata filter.
If a vector value is included, it will overwrite the previous value. If `set_metadata` is included, only the specified metadata fields are modified, and if a specified metadata field does not exist, it is added.
For guidance and examples, see [Update data](https://docs.pinecone.io/guides/manage-data/update-data).

<RequestExample>
  ```shell curl theme={null}
  # To get the unique host for an index,
  # see https://docs.pinecone.io/guides/manage-data/target-an-index
  PINECONE_API_KEY="YOUR_API_KEY"
  INDEX_HOST="INDEX_HOST"

  curl "https://$INDEX_HOST/vectors/update" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "Content-Type: application/json" \
    -H "X-Pinecone-Api-Version: 2026-04" \
    -d '{
          "id": "id-3",
          "values": [4.0, 2.0],
          "setMetadata": {"type": "comedy"},
          "namespace": "example-namespace"
        }'
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {}
  ```
</ResponseExample>


# Describe a model
Source: https://docs.pinecone.io/reference/api/2026-04/inference/describe_model

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/inference_2026-04.oas.yaml get /models/{model_name}
Get a description of a model hosted by Pinecone. 

You can use hosted models as an integrated part of Pinecone operations or for standalone embedding and reranking. For more details, see [Vector embedding](https://docs.pinecone.io/guides/index-data/indexing-overview#vector-embedding) and [Rerank results](https://docs.pinecone.io/guides/search/rerank-results).

<RequestExample>
  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"

  curl "https://api.pinecone.io/models/llama-text-embed-v2" \
      -H "Api-Key: $PINECONE_API_KEY" \
      -H "X-Pinecone-Api-Version: 2026-04"
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "model": "llama-text-embed-v2",
    "short_description": "A high performance dense embedding model optimized for multilingual and cross-lingual text question-answering retrieval with support for long documents (up to 2048 tokens) and dynamic embedding size (Matryoshka Embeddings).",
    "type": "embed",
    "vector_type": "dense",
    "default_dimension": 1024,
    "modality": "text",
    "max_sequence_length": 2048,
    "max_batch_size": 96,
    "provider_name": "NVIDIA",
    "supported_metrics": [
      "Cosine",
      "DotProduct"
    ],
    "supported_dimensions": [
      384,
      512,
      768,
      1024,
      2048
    ],
    "supported_parameters": [
      {
        "parameter": "input_type",
        "required": true,
        "type": "one_of",
        "value_type": "string",
        "allowed_values": [
          "query",
          "passage"
        ]
      },
      {
        "parameter": "truncate",
        "required": false,
        "default": "END",
        "type": "one_of",
        "value_type": "string",
        "allowed_values": [
          "END",
          "NONE",
          "START"
        ]
      },
      {
        "parameter": "dimension",
        "required": false,
        "default": 1024,
        "type": "one_of",
        "value_type": "integer",
        "allowed_values": [
          384,
          512,
          768,
          1024,
          2048
        ]
      }
    ]
  }
  ```
</ResponseExample>


# Generate vectors
Source: https://docs.pinecone.io/reference/api/2026-04/inference/generate-embeddings

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/inference_2026-04.oas.yaml post /embed
Generate vector embeddings for input data. This endpoint uses Pinecone's [hosted embedding models](https://docs.pinecone.io/guides/index-data/create-an-index#embedding-models).

<RequestExample>
  ```shell curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"

  curl https://api.pinecone.io/embed \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "Content-Type: application/json" \
    -H "X-Pinecone-Api-Version: 2026-04" \
    -d '{
        "model": "llama-text-embed-v2",
        "parameters": {
          "input_type": "passage",
          "truncate": "END"
        },
        "inputs": [
          {"text": "Apple is a popular fruit known for its sweetness and crisp texture."},
          {"text": "The tech company Apple is known for its innovative products like the iPhone."},
          {"text": "Many people enjoy eating apples as a healthy snack."},
          {"text": "Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces."},
          {"text": "An apple a day keeps the doctor away, as the saying goes."},
          {"text": "Apple Computer Company was founded on April 1, 1976, by Steve Jobs, Steve Wozniak, and Ronald Wayne as a partnership."}
        ]
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "data": [
      {
        "values": [
          0.04925537109375,
          -0.01313018798828125,
          -0.0112762451171875,
          ...
        ]
      }, 
      ...
    ],
    "model": "llama-text-embed-v2",
    "usage": {
      "total_tokens": 130
    }
  }
  ```
</ResponseExample>


# List available models
Source: https://docs.pinecone.io/reference/api/2026-04/inference/list_models

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/inference_2026-04.oas.yaml get /models
List the embedding and reranking models hosted by Pinecone. 

You can use hosted models as an integrated part of Pinecone operations or for standalone embedding and reranking. For more details, see [Vector embedding](https://docs.pinecone.io/guides/index-data/indexing-overview#vector-embedding) and [Rerank results](https://docs.pinecone.io/guides/search/rerank-results).

<RequestExample>
  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"

  curl "https://api.pinecone.io/models" \
      -H "Api-Key: $PINECONE_API_KEY" \
      -H "X-Pinecone-Api-Version: 2026-04"
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "models": [
      {
        "model": "llama-text-embed-v2",
        "short_description": "A high performance dense embedding model optimized for multilingual and cross-lingual text question-answering retrieval with support for long documents (up to 2048 tokens) and dynamic embedding size (Matryoshka Embeddings).",
        "type": "embed",
        "vector_type": "dense",
        "default_dimension": 1024,
        "modality": "text",
        "max_sequence_length": 2048,
        "max_batch_size": 96,
        "provider_name": "NVIDIA",
        "supported_metrics": [
          "Cosine",
          "DotProduct"
        ],
        "supported_dimensions": [
          384,
          512,
          768,
          1024,
          2048
        ],
        "supported_parameters": [
          {
            "parameter": "input_type",
            "required": true,
            "type": "one_of",
            "value_type": "string",
            "allowed_values": [
              "query",
              "passage"
            ]
          },
          {
            "parameter": "truncate",
            "required": false,
            "default": "END",
            "type": "one_of",
            "value_type": "string",
            "allowed_values": [
              "END",
              "NONE",
              "START"
            ]
          },
          {
            "parameter": "dimension",
            "required": false,
            "default": 1024,
            "type": "one_of",
            "value_type": "integer",
            "allowed_values": [
              384,
              512,
              768,
              1024,
              2048
            ]
          }
        ]
      },
      {
        "model": "multilingual-e5-large",
        "short_description": "A high-performance dense embedding model trained on a mixture of multilingual datasets. It works well on messy data and short queries expected to return medium-length passages of text (1-2 paragraphs)",
        "type": "embed",
        "vector_type": "dense",
        "default_dimension": 1024,
        "modality": "text",
        "max_sequence_length": 507,
        "max_batch_size": 96,
        "provider_name": "Microsoft",
        "supported_metrics": [
          "Cosine",
          "Euclidean"
        ],
        "supported_dimensions": [
          1024
        ],
        "supported_parameters": [
          {
            "parameter": "input_type",
            "required": true,
            "type": "one_of",
            "value_type": "string",
            "allowed_values": [
              "query",
              "passage"
            ]
          },
          {
            "parameter": "truncate",
            "required": false,
            "default": "END",
            "type": "one_of",
            "value_type": "string",
            "allowed_values": [
              "END",
              "NONE"
            ]
          }
        ]
      },
      {
        "model": "pinecone-sparse-english-v0",
        "short_description": "A sparse embedding model for converting text to sparse vectors for keyword or hybrid semantic/keyword search. Built on the innovations of the DeepImpact architecture.",
        "type": "embed",
        "vector_type": "sparse",
        "modality": "text",
        "max_sequence_length": 512,
        "max_batch_size": 96,
        "provider_name": "Pinecone",
        "supported_metrics": [
          "DotProduct"
        ],
        "supported_parameters": [
          {
            "parameter": "input_type",
            "required": true,
            "type": "one_of",
            "value_type": "string",
            "allowed_values": [
              "query",
              "passage"
            ]
          },
          {
            "parameter": "truncate",
            "required": false,
            "default": "END",
            "type": "one_of",
            "value_type": "string",
            "allowed_values": [
              "END",
              "NONE"
            ]
          },
          {
            "parameter": "return_tokens",
            "required": false,
            "default": false,
            "type": "any",
            "value_type": "boolean"
          }
        ]
      },
      {
        "model": "bge-reranker-v2-m3",
        "short_description": "A high-performance, multilingual reranking model that works well on messy data and short queries expected to return medium-length passages of text (1-2 paragraphs)",
        "type": "rerank",
        "modality": "text",
        "max_sequence_length": 1024,
        "max_batch_size": 100,
        "provider_name": "BAAI",
        "supported_parameters": [
          {
            "parameter": "truncate",
            "required": false,
            "default": "NONE",
            "type": "one_of",
            "value_type": "string",
            "allowed_values": [
              "END",
              "NONE"
            ]
          }
        ]
      },
      {
        "model": "cohere-rerank-3.5",
        "short_description": "Cohere's leading reranking model, balancing performance and latency for a wide range of enterprise search applications.",
        "type": "rerank",
        "modality": "text",
        "max_sequence_length": 40000,
        "max_batch_size": 200,
        "provider_name": "Cohere",
        "supported_parameters": [
          {
            "parameter": "max_chunks_per_doc",
            "required": false,
            "default": 3072,
            "type": "numeric_range",
            "value_type": "integer",
            "min": 1,
            "max": 3072
          }
        ]
      },
      {
        "model": "pinecone-rerank-v0",
        "short_description": "A state of the art reranking model that out-performs competitors on widely accepted benchmarks. It can handle chunks up to 512 tokens (1-2 paragraphs)",
        "type": "rerank",
        "modality": "text",
        "max_sequence_length": 512,
        "max_batch_size": 100,
        "provider_name": "Pinecone",
        "supported_parameters": [
          {
            "parameter": "truncate",
            "required": false,
            "default": "END",
            "type": "one_of",
            "value_type": "string",
            "allowed_values": [
              "END",
              "NONE"
            ]
          }
        ]
      }
    ]
  }
  ```
</ResponseExample>


# Rerank results
Source: https://docs.pinecone.io/reference/api/2026-04/inference/rerank

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/inference_2026-04.oas.yaml post /rerank
Rerank results according to their relevance to a query.

For guidance and examples, see [Rerank results](https://docs.pinecone.io/guides/search/rerank-results).

<RequestExample>
  ```shell curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"

  curl https://api.pinecone.io/rerank \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "X-Pinecone-Api-Version: 2026-04" \
    -H "Api-Key: $PINECONE_API_KEY" \
  -d '{
    "model": "bge-reranker-v2-m3",
    "query": "The tech company Apple is known for its innovative products like the iPhone.",
    "return_documents": true,
    "top_n": 4,
    "documents": [
      {"id": "vec1", "text": "Apple is a popular fruit known for its sweetness and crisp texture."},
      {"id": "vec2", "text": "Many people enjoy eating apples as a healthy snack."},
      {"id": "vec3", "text": "Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces."},
      {"id": "vec4", "text": "An apple a day keeps the doctor away, as the saying goes."}
    ],
    "parameters": {
      "truncate": "END"
    }
  }'
  ```
</RequestExample>

<ResponseExample>
  ```JSON curl theme={null}
  {
    "data":[
      {
        "index":2,
        "document":{
          "id":"vec3",
          "text":"Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces."
        },
        "score":0.47654688
      },
      {
        "index":0,
        "document":{
          "id":"vec1",
          "text":"Apple is a popular fruit known for its sweetness and crisp texture."
        },
        "score":0.047963805
      },
      {
        "index":3,
        "document":{
          "id":"vec4",
          "text":"An apple a day keeps the doctor away, as the saying goes."
        },
        "score":0.007587992
      },
      {
        "index":1,
        "document":{
          "id":"vec2",
          "text":"Many people enjoy eating apples as a healthy snack."
        },
        "score":0.0006491712
      }
    ],
    "usage":{
      "rerank_units":1
    }
  }
  ```
</ResponseExample>


# Authentication
Source: https://docs.pinecone.io/reference/api/authentication

Pinecone API authentication guide covering API key generation, SDK client setup, and HTTP header configuration for authorized requests.

All requests to [Pinecone APIs](/reference/api/introduction) must contain a valid [API key](/guides/production/security-overview#api-keys) for the target project.

## Get an API key

[Create a new API key](https://app.pinecone.io/organizations/-/projects/-/keys) in the Pinecone console, or use the connect widget below to generate a key.

<div>
  <div>
    <div>
      <div />
    </div>
  </div>
</div>

Copy your generated key:

```
PINECONE_API_KEY="{{YOUR_API_KEY}}"

# This API key has ReadWrite access to all indexes in your project.
```

## Initialize a client

When using a [Pinecone SDK](/reference/pinecone-sdks), initialize a client object with your API key and then reuse the authenicated client in subsquent function calls. For example:

<CodeGroup>
  ```Python Python theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone
  from pinecone import ServerlessSpec

  pc = Pinecone(api_key='YOUR_API_KEY')

  # Creates an index using the API key stored in the client 'pc'.
  pc.create_index(
      name="docs-example",
      dimension=1536,
      metric="cosine",
      spec=ServerlessSpec(
          cloud='aws', 
          region='us-east-1'
      ) 
  ) 
  ```

  ```JavaScript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone';

  const pc = new Pinecone({
      apiKey: 'YOUR_API_KEY' 
  });

  // Creates an index using the API key stored in the client 'pc'.
  await pc.createIndex({
      name: 'docs-example',
      dimension: 1536,
      metric: 'cosine',
      spec: { 
          serverless: { 
              cloud: 'aws', 
              region: 'us-east-1' 
          }
      } 
  }) 
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Pinecone;
  import org.openapitools.db_control.client.model.IndexModel;
  import org.openapitools.db_control.client.model.DeletionProtection;

  public class CreateServerlessIndexExample {
      public static void main(String[] args) {
          Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build();

          // Creates an index using the API key stored in the client 'pc'.
          pc.createServerlessIndex("docs-example", "cosine", 1536, "aws", "us-east-1");
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "fmt"
      "log"

      "github.com/pinecone-io/go-pinecone/v3/pinecone"
  )

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

  	indexName := "docs-example"
  	vectorType := "dense"
      dimension := int32(1536)
      metric := pinecone.Cosine
  	deletionProtection := pinecone.DeletionProtectionDisabled

      idx, err := pc.CreateServerlessIndex(ctx, &pinecone.CreateServerlessIndexRequest{
          Name:               indexName,
          VectorType:         &vectorType,
          Dimension:          &dimension,
          Metric:             &metric,
          Cloud:              pinecone.Aws,
          Region:             "us-east-1",
          DeletionProtection: &deletionProtection,
      })
      if err != nil {
          log.Fatalf("Failed to create serverless index: %v", err)
      } else {
          fmt.Printf("Successfully created serverless index: %v", idx.Name)
      }
  }
  ```

  ```shell curl theme={null}
  curl -s "https://api.pinecone.io/indexes" \
      -H "Api-Key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -H "X-Pinecone-Api-Version: 2025-10" \
      -d '{
          "name":  "docs-example",
          "dimension": 1536,
          "metric": "cosine",
          "spec": {
              "serverless": {
                 "cloud":"aws",
                 "region": "us-east-1"
              }
          }
      }'
  ```
</CodeGroup>

## Add headers to an HTTP request

All HTTP requests to Pinecone APIs must contain an `Api-Key` header that specifies a valid [API key](/guides/production/security-overview#api-keys) and must be encoded as JSON with the `Content-Type: application/json` header. For example:

```shell curl theme={null}
curl https://api.pinecone.io/indexes \
   -H "Content-Type: application/json" \
   -H "Api-Key: $PINECONE_API_KEY" \
  -H "X-Pinecone-Api-Version: 2025-10" \
   -d '{
         "name":  "docs-example",
         "dimension": 1536,
         "metric": "cosine",
         "spec": {
            "serverless": {
               "cloud":"aws",
               "region": "us-east-1"
            }
         }
      }'
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Initialization errors due to outdated SDKs">
    Older versions of Pinecone required you to initialize a client with an `init` method that takes both `api_key` and `environment` parameters, for example:

    <CodeGroup>
      ```python Python theme={null}
      # Legacy initialization
      import pinecone

      pc = pinecone.init(
          api_key="PINECONE_API_KEY",
          environment="PINECONE_ENVIRONMENT"
      )
      ```

      ```javascript JavaScript theme={null}
      // Legacy initialization
      import { Pinecone } from '@pinecone-database/pinecone';

      const pineconeClient = new PineconeClient();
      await pineconeClient.init({
          apiKey: 'PINECONE_API_KEY',
          environment: 'PINECONE_ENVIRONMENT',
      });
      ```
    </CodeGroup>

    In more recent versions of Pinecone, this has changed. Initialization no longer requires an `init` step, and cloud environment is defined for each index rather than an entire project. Client initialization now only requires an `api_key` parameter, for example:

    <CodeGroup>
      ```python Python theme={null}
      # New initialization
      from pinecone import Pinecone

      pc = Pinecone(api_key="YOUR_API_KEY")
      ```

      ```javascript JavaScript theme={null}
      // New initialization
      import { Pinecone } from '@pinecone-database/pinecone';

      const pc = new Pinecone({
          apiKey: 'YOUR_API_KEY' 
      });
      ```
    </CodeGroup>

    If you are receiving errors about initialization, upgrade your [Pinecone SDK](/reference/pinecone-sdks) to the latest version, for example:

    <CodeGroup>
      ```shell Python theme={null}
      # Upgrade Pinecone SDK
      pip install pinecone --upgrade
      ```

      ```shell JavaScript theme={null}
      # Upgrade Pinecone SDK
      npm install @pinecone-database/pinecone@latest
      ```
    </CodeGroup>

    Also, note that some third-party tutorials and examples still reference the older initialization method. In such cases, follow the example above and the examples throughout the Pinecone documentation instead.
  </Accordion>
</AccordionGroup>


# Pinecone Database limits
Source: https://docs.pinecone.io/reference/api/database-limits

Reference for Pinecone Database limits, covering upsert, query, fetch, delete, import, namespace, and rate limits for serverless indexes.

This page describes different types of limits for Pinecone Database.

<Note>
  **Looking for a specific limit?**

  * To compare monthly included usage by plan, start with [read units](#read-units-per-month-per-org), [write units](#write-units-per-month-per-org), and [model usage limits](#monthly-usage-limits).
  * If you received a `429` error, check [rate limits](#rate-limits), especially request-per-second limits for query, upsert, update, delete, fetch, and list.
  * For projects, users, indexes, namespaces, storage, backups, and collections, see [object limits](#object-limits).
  * For batch sizes, metadata filters, and identifier lengths, see [operation limits](#operation-limits) and [identifier limits](#identifier-limits).
</Note>

## Rate limits

Rate limits help protect your applications from misuse and maintain the health of our shared serverless infrastructure. These limits are designed to support typical production workloads while ensuring reliable performance for all users.

**Most rate limits can be adjusted upon request.** If you need higher limits to scale your application, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) with details about your use case. Pinecone is committed to supporting your growth and can often accommodate higher throughput requirements.

Rate limits vary based on [pricing plan](https://www.pinecone.io/pricing/) and apply to [serverless indexes](/guides/index-data/indexing-overview) only.

<Note>
  Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide.
</Note>

### Data plane operations: request-per-second limits

Pinecone enforces rate limits on the number of API requests per second at the namespace level for data plane operations (query, upsert, delete, and update). These limits provide protection against excessive request rates.

#### Affected operations

The following operations are subject to request-per-second rate limiting:

| Operation | Scope         | Limit |
| --------- | ------------- | ----- |
| Query     | Per namespace | 100   |
| Upsert    | Per namespace | 100   |
| Delete    | Per namespace | 100   |
| Update    | Per namespace | 100   |

#### Error response

When you exceed the request-per-second limit, you'll receive an HTTP `429 - TOO_MANY_REQUESTS` response. The error message indicates which operation exceeded the limit and includes the namespace name and limit value. See the individual limit sections below for specific error message formats.

#### How request-per-second limits work with limits on read and write units

Request-per-second limits are enforced in addition to existing read unit and write unit limits. Requests must not exceed any applicable limits:

* Index-level limits - read and write unit limits, per index
* Namespace-level limits - read and write unit limits, per namespace
* Request-per-second limits - requests per second, per namespace

If any limit is exceeded, the request fails with a 429 error.

#### Recommendations

If you're hitting request-per-second limits:

1. Implement retry logic. Use exponential backoff to handle rate limit errors gracefully. See [Error Handling Guide](/guides/production/error-handling#implement-retry-logic).
2. Pace your requests. Add client-side rate limiting to stay under limits.
3. Consider [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes), which don't have request-per-second limits and provide dedicated capacity for high-throughput workloads.
4. If you need higher limits, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) with details about your use case.

### All rate limits

#### Monthly usage limits

| Metric                                                                        | Starter plan   | Builder plan   | Standard plan  | Enterprise plan |
| :---------------------------------------------------------------------------- | :------------- | :------------- | :------------- | :-------------- |
| [Read units per month per org](#read-units-per-month-per-org)                 | 1,000,000      | 2,000,000      | Unlimited      | Unlimited       |
| [Write units per month per org](#write-units-per-month-per-org)               | 2,000,000      | 5,000,000      | Unlimited      | Unlimited       |
| [Embedding tokens per month per model](#embedding-tokens-per-month-per-model) | 5,000,000      | 10,000,000     | Unlimited      | Unlimited       |
| [Rerank requests per month per model](#rerank-requests-per-month-per-model)   | Model-specific | Model-specific | Model-specific | Model-specific  |

#### Data operation throughput limits

| Metric                                                                                                        | Starter plan | Builder plan | Standard plan | Enterprise plan |
| :------------------------------------------------------------------------------------------------------------ | :----------- | :----------- | :------------ | :-------------- |
| [Upsert size per second per namespace](#upsert-size-per-second-per-namespace)                                 | 50 MB        | 50 MB        | 50 MB         | 50 MB           |
| [Query read units per second per index](#query-read-units-per-second-per-index)                               | 2,000        | 2,000        | 2,000         | 2,000           |
| [Query requests per second per namespace](#query-requests-per-second-per-namespace)                           | 100          | 100          | 100           | 100             |
| [Update records per second per namespace](#update-records-per-second-per-namespace)                           | 100          | 100          | 100           | 100             |
| [Update requests per second per namespace](#update-requests-per-second-per-namespace)                         | 100          | 100          | 100           | 100             |
| [Update by metadata requests per second per namespace](#update-by-metadata-requests-per-second-per-namespace) | 5            | 5            | 5             | 5               |
| [Update by metadata requests per second per index](#update-by-metadata-requests-per-second-per-index)         | 500          | 500          | 500           | 500             |
| [Upsert requests per second per namespace](#upsert-requests-per-second-per-namespace)                         | 100          | 100          | 100           | 100             |
| [Fetch requests per second per index](#fetch-requests-per-second-per-index)                                   | 100          | 100          | 100           | 100             |
| [List requests per second per index](#list-requests-per-second-per-index)                                     | 200          | 200          | 200           | 200             |
| [Describe index stats requests per second per index](#describe-index-stats-requests-per-second-per-index)     | 100          | 100          | 100           | 100             |
| [Delete requests per second per namespace](#delete-requests-per-second-per-namespace)                         | 100          | 100          | 100           | 100             |
| [Delete records per second per namespace](#delete-records-per-second-per-namespace)                           | 5,000        | 5,000        | 5,000         | 5,000           |
| [Delete records per second per index](#delete-records-per-second-per-index)                                   | 5,000        | 5,000        | 5,000         | 5,000           |
| [Delete by metadata requests per second per namespace](#delete-by-metadata-requests-per-second-per-namespace) | 5            | 5            | 5             | 5               |
| [Delete by metadata requests per second per index](#delete-by-metadata-requests-per-second-per-index)         | 500          | 500          | 500           | 500             |

#### Model throughput limits

| Metric                                                                          | Starter plan   | Builder plan   | Standard plan  | Enterprise plan |
| :------------------------------------------------------------------------------ | :------------- | :------------- | :------------- | :-------------- |
| [Embedding tokens per minute per model](#embedding-tokens-per-minute-per-model) | Model-specific | Model-specific | Model-specific | Model-specific  |
| [Rerank requests per minute per model](#rerank-requests-per-minute-per-model)   | Model-specific | Model-specific | Model-specific | Model-specific  |

### Read units per month per org

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 1,000,000    | 2,000,000    | Unlimited     | Unlimited       |

[Read units](/guides/manage-cost/understanding-cost#read-units) measure the compute, I/O, and network resources used by [fetch](/guides/manage-data/fetch-data), [query](/guides/search/search-overview), and [list](/guides/manage-data/list-record-ids) requests to serverless indexes. When you reach the monthly read unit limit for an organization, fetch, query, and list requests to serverless indexes in the organization will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached your read unit limit for the current month limit. 
  To continue reading data, upgrade your plan. 
  ```
</Accordion>

To continue reading from serverless indexes in the organization, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan).

To check how close you are to the monthly read unit limit for your organization, do the following:

1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects).
2. Select the project.
3. Select any index in the project.
4. Look under **Usage**.

<Note>
  Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide.
</Note>

### Write units per month per org

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 2,000,000    | 5,000,000    | Unlimited     | Unlimited       |

[Write units](/guides/manage-cost/understanding-cost#write-units) measure the storage and compute resources used by [upsert](/guides/index-data/upsert-data), [update](/guides/manage-data/update-data), and [delete](/guides/manage-data/delete-data) requests to serverless indexes. When you reach the monthly write unit limit for an organization, upsert, update, and delete requests to serverless indexes in the organization will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached your write unit limit for the current month. 
  To continue writing data, upgrade your plan.
  ```
</Accordion>

To continue writing data to serverless indexes in the organization, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan).

To check how close you are to the monthly write unit limit for your organization, do the following:

1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects).
2. Select the project.
3. Select any index in the project.
4. Look under **Usage**.

### Upsert size per second per namespace

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 50 MB        | 50 MB        | 50 MB         | 50 MB           |

When you reach the per second [upsert](/guides/index-data/upsert-data) size for a namespace in an index, additional upserts will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max upsert size limit per second for index <index name>. 
  Pace your upserts or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Query read units per second per index

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 2,000        | 2,000        | 2,000         | 2,000           |

Pinecone measures [query](/guides/search/search-overview) usage in [read units](/guides/manage-cost/understanding-cost#read-units). When you reach the per second limit for queries across all namespaces in an index, additional queries will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max query read units per second for index <index name>. 
  Pace your queries or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

To check how many read units a query consumes, [check the query response](/guides/manage-cost/monitor-usage-and-costs#read-units).

<Note>
  Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide.
</Note>

### Query requests per second per namespace

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 100          | 100          | 100           | 100             |

When you reach the per second [query](/guides/search/search-overview) limit for a namespace in an index, additional queries will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the query QPS limit for namespace {namespace_name} ({limit} QPS). Pace your queries,
  consider Dedicated Read Nodes for your index, or contact Pinecone Support
  (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

<Note>
  Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide.
</Note>

### Update records per second per namespace

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 100          | 100          | 100           | 100             |

When you reach the per second [update](/guides/manage-data/update-data) limit for a namespace in an index, additional updates will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max update records per second for namespace <namespace name>. 
  Pace your update requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Update requests per second per namespace

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 100          | 100          | 100           | 100             |

When you reach the per second [update](/guides/manage-data/update-data) request limit for a namespace in an index, additional update requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the update QPS limit for namespace {namespace_name} ({limit} QPS). Pace your update requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

<Tip>
  If you need to update most of the records in a large namespace, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) for help creating an export to enable a faster and more cost-effective approach.
</Tip>

### Update by metadata requests per second per namespace

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 5            | 5            | 5             | 5               |

When you reach the per second [update by metadata](/guides/manage-data/update-data#update-metadata-across-multiple-records) request limit for a namespace in an index, additional update by metadata requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max update by metadata requests per second for namespace <namespace name>. Pace your update by metadata requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Update by metadata requests per second per index

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 500          | 500          | 500           | 500             |

When you reach the per second [update by metadata](/guides/manage-data/update-data#update-metadata-across-multiple-records) request limit across all namespaces in an index, additional update by metadata requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max update by metadata requests per second for index <index name>. Pace your update by metadata requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Upsert requests per second per namespace

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 100          | 100          | 100           | 100             |

When you reach the per second [upsert](/guides/index-data/upsert-data) request limit for a namespace in an index, additional upsert requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the upsert QPS limit for namespace {namespace_name} ({limit} QPS). Pace your upsert requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Fetch requests per second per index

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 100          | 100          | 100           | 100             |

When you reach the per second [fetch](/guides/manage-data/fetch-data) limit across all namespaces in an index, additional fetch requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max fetch requests per second for index <index name>.
  Pace your fetch requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

<Note>
  Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide.
</Note>

### List requests per second per index

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 200          | 200          | 200           | 200             |

When you reach the per second [list](/guides/manage-data/list-record-ids) limit across all namespaces in an index, additional list requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max list requests per second for index <index name>.
  Pace your list requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

<Note>
  Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide.
</Note>

### Describe index stats requests per second per index

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 100          | 100          | 100           | 100             |

When you reach the per second [describe index stats](/reference/api/2024-10/data-plane/describeindexstats) limit across all namespaces in an index, additional describe index stats requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max describe_index_stats requests per second for index <index>. 
  Pace your describe_index_stats requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Delete requests per second per namespace

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 100          | 100          | 100           | 100             |

When you reach the per second [delete](/guides/manage-data/delete-data) request limit for a namespace in an index, additional delete requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the delete QPS limit for namespace {namespace_name} ({limit} QPS). Pace your delete requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Delete records per second per namespace

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 5000         | 5000         | 5000          | 5000            |

When you reach the per second [delete](/guides/manage-data/delete-data) limit for a namespace in an index, additional deletes will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max delete records per second for namespace <namespace name>. 
  Pace your delete requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Delete records per second per index

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 5000         | 5000         | 5000          | 5000            |

When you reach the per second [delete](/guides/manage-data/delete-data) limit across all namespaces in an index, additional deletes will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max delete records per second for index <index name>. 
  Pace your delete requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Delete by metadata requests per second per namespace

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 5            | 5            | 5             | 5               |

When you reach the per second [delete by metadata](/guides/manage-data/delete-data#delete-records-by-metadata) request limit for a namespace in an index, additional delete by metadata requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max delete by metadata requests per second for namespace <namespace name>. Pace your delete by metadata requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Delete by metadata requests per second per index

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 500          | 500          | 500           | 500             |

When you reach the per second [delete by metadata](/guides/manage-data/delete-data#delete-records-by-metadata) request limit across all namespaces in an index, additional delete by metadata requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max delete by metadata requests per second for index <index name>. Pace your delete by metadata requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Embedding tokens per minute per model

| Embedding model              | Input type | Starter plan | Builder plan | Standard plan | Enterprise plan |
| :--------------------------- | :--------- | :----------- | :----------- | :------------ | :-------------- |
| `llama-text-embed-v2`        | Passage    | 250,000      | 250,000      | 1,000,000     | 1,000,000       |
|                              | Query      | 50,000       | 50,000       | 250,000       | 250,000         |
| `multilingual-e5-large`      | Passage    | 250,000      | 250,000      | 1,000,000     | 1,000,000       |
|                              | Query      | 50,000       | 50,000       | 250,000       | 250,000         |
| `pinecone-sparse-english-v0` | Passage    | 250,000      | 250,000      | 3,000,000     | 3,000,000       |
|                              | Query      | 250,000      | 250,000      | 3,000,000     | 3,000,000       |

When you reach the per minute token limit for an [embedding model](/guides/index-data/create-an-index#embedding-models) hosted by Pinecone, additional embeddings will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max embedding tokens per minute (<limit>) model '<model name>'' and input type '<passage|query>' for the current project. 
  To increase this limit, upgrade your plan.
  ```
</Accordion>

To increase this limit, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). Otherwise, you can handle this limit by [implementing retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic).

### Embedding tokens per month per model

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 5,000,000    | 10,000,000   | Unlimited     | Unlimited       |

When you reach the monthly token limit for an [embedding model](/guides/index-data/create-an-index#embedding-models) hosted by Pinecone, additional embeddings will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the embedding token limit (<limit>) for model <model name> for the current month. 
  To continue using this model, upgrade your plan.
  ```
</Accordion>

To increase this limit, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan) or [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Rerank requests per minute per model

| Reranking model        | Starter plan  | Builder plan  | Standard plan | Enterprise plan |
| :--------------------- | :------------ | :------------ | :------------ | :-------------- |
| `cohere-rerank-4-fast` | Not available | Not available | 300           | 300             |
| `cohere-rerank-3.5`    | Not available | Not available | 300           | 300             |
| `bge-reranker-v2-m3`   | 60            | 60            | 60            | 60              |
| `pinecone-rerank-v0`   | 60            | Not available | 60            | 60              |

When you reach the per minute request limit for a [reranking model](/guides/search/rerank-results#reranking-models) hosted by Pinecone, additional reranking requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max rerank requests per minute (<limit>) for model '<model name>' for the current project. 
  To increase this limit, upgrade your plan.
  ```
</Accordion>

To increase this limit, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan).

### Rerank requests per month per model

| Reranking model        | Starter plan  | Builder plan  | Standard plan | Enterprise plan |
| :--------------------- | :------------ | :------------ | :------------ | :-------------- |
| `cohere-rerank-4-fast` | Not available | Not available | Unlimited     | Unlimited       |
| `cohere-rerank-3.5`    | Not available | Not available | Unlimited     | Unlimited       |
| `bge-reranker-v2-m3`   | 500           | 1,000         | Unlimited     | Unlimited       |
| `pinecone-rerank-v0`   | 500           | Not available | Unlimited     | Unlimited       |

When you reach the monthly request limit for a [reranking model](/guides/search/rerank-results#reranking-models) hosted by Pinecone, additional reranking requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the rerank request limit (<limit>) for model <model name> for the current month. 
  To continue using this model, upgrade your plan.
  ```
</Accordion>

To increase this limit, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan) or [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Inference requests per second or minute, per project

| Metric                        | Starter plan | Builder plan | Standard plan | Enterprise plan |
| :---------------------------- | :----------- | :----------- | :------------ | :-------------- |
| Inference requests per second | 100          | 100          | 100           | 100             |
| Inference requests per minute | 2000         | 2000         | 2000          | 2000            |

When you reach the per second or per minute request limit, inference requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max inference requests per second (<limit>) for the current project.
  ```
</Accordion>

<Note>
  This error indicates per second or per minute, as applicable.
</Note>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic).

## Object limits

Object limits are restrictions on the number or size of objects in Pinecone. Object limits vary based on [pricing plan](https://www.pinecone.io/pricing/).

| Metric                                                                         | Starter plan | Builder plan | Standard plan | Enterprise plan |
| :----------------------------------------------------------------------------- | :----------- | :----------- | :------------ | :-------------- |
| [Projects per organization](#projects-per-organization)                        | 1            | 5            | 20            | 100             |
| [Users per organization](#users-per-organization)                              | 2            | 5            | Unlimited     | Unlimited       |
| [Serverless indexes per project](#serverless-indexes-per-project) <sup>1</sup> | 5            | 10           | 20            | 200             |
| [Serverless index storage per org](#serverless-index-storage-per-org)          | 2 GB         | 10 GB        | N/A           | N/A             |
| [Namespaces per serverless index](#namespaces-per-serverless-index)            | 100          | 1,000        | 100,000       | 100,000         |
| [Serverless backups per project](#serverless-backups-per-project)              | N/A          | N/A          | 500           | 1000            |
| [Collections per project](#collections-per-project)                            | 100          | N/A          | N/A           | N/A             |

<sup>1 On the Starter plan, all serverless indexes must be in the `us-east-1` region of AWS. Builder, Standard, and Enterprise plans can create indexes in any [supported region](/guides/index-data/create-an-index#cloud-regions).</sup><br />

### Projects per organization

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 1            | 5            | 20            | 100             |

When you reach this quota for an organization, trying to [create projects](/guides/projects/create-a-project) will fail and return a `403 - QUOTA_EXCEEDED` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max projects allowed in organization <org name>. 
  To add more projects, upgrade your plan.
  ```
</Accordion>

To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan) or [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Users per organization

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 2            | 5            | Unlimited     | Unlimited       |

When you reach this quota for an organization, trying to add users to the organization will fail. To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan).

### Serverless indexes per project

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 5            | 10           | 20            | 200             |

When you reach this quota for a project, trying to [create serverless indexes](/guides/index-data/create-an-index#create-a-serverless-index) in the project will fail and return a `403 - QUOTA_EXCEEDED` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max serverless indexes allowed in project <project>. 
  Use namespaces to partition your data into logical groups, or upgrade your plan to add more serverless indexes.
  ```
</Accordion>

To stay under this quota, consider using [namespaces](/guides/index-data/create-an-index#namespaces) instead of creating multiple indexes. Namespaces let you partition your data into logical groups within a single index. This approach not only helps you stay within index limits, but can also improve query performance and lower costs by limiting searches to relevant data subsets.

To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan).

### Serverless index storage per org

<Note>This limit applies to organizations on the Starter and Builder plans only.</Note>

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 2 GB         | 10 GB        | N/A           | N/A             |

When you've reached this quota for an organization, updates and upserts into serverless indexes will fail and return a `403 - QUOTA_EXCEEDED` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max storage allowed for organization <org name>. 
  To update or upsert new data, delete records or upgrade your plan.
  ```
</Accordion>

To continue writing data into your serverless indexes, [delete records](/guides/manage-data/delete-data) to bring your organization under the limit or [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan).

### Namespaces per serverless index

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 100          | 1,000        | 100,000       | 100,000         |

When you reach this quota for a serverless index, trying to [upsert records into a new namespace](/guides/index-data/upsert-data) in the index will fail and return a `403 - QUOTA_EXCEEDED` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max namespaces allowed in serverless index <index name>. 
  To add more namespaces, upgrade your plan.
  ```
</Accordion>

To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan).

<Note>
  [Namespaces per serverless index](/reference/api/database-limits#namespaces-per-serverless-index) vary by plan. On the Standard and Enterprise plans, Pinecone can accommodate million-scale namespaces and beyond for specific use cases. If your application requires more than 100,000 namespaces, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).
</Note>

### Serverless backups per project

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| N/A          | N/A          | 500           | 1000            |

Backups are not available on the Starter or Builder plans. On the Standard and Enterprise plans, when you reach this quota for a project, trying to [create serverless backups](/guides/manage-data/back-up-an-index) in the project will fail and return a `403 - QUOTA_EXCEEDED` status with the following error:

<Accordion title="Error response">
  ```
  Backup failed to create. Quota for number of backups per index exceeded.
  ```
</Accordion>

### Collections per project

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 100          | N/A          | N/A           | N/A             |

When you reach this quota for a project, trying to [create collections](/guides/manage-data/back-up-an-index) in the project will fail and return a `403 - QUOTA_EXCEEDED` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max collections allowed in project <project name>. 
  To add more collections, upgrade your plan.
  ```
</Accordion>

To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan).

## Operation limits

Operation limits are restrictions on the size, number, or other characteristics of operations in Pinecone. Operation limits are fixed and do not vary based on pricing plan.

### Upsert limits

| Metric                                                             | Limit                                                         |
| :----------------------------------------------------------------- | :------------------------------------------------------------ |
| Max [batch size](/guides/index-data/upsert-data#upsert-in-batches) | 2 MB or 1000 records with vectors <br /> 96 records with text |
| Max documents per upsert request                                   | 1000                                                          |
| Max document upsert request size                                   | 2 MB                                                          |
| Max document size                                                  | 2 MB                                                          |
| Max `full_text_search` string fields per schema                    | 100                                                           |
| Max size per `full_text_search` string field                       | 100 KB                                                        |
| Max tokens per `full_text_search` string field                     | 10,000                                                        |
| Max bytes per token                                                | 256 bytes                                                     |
| Max filterable metadata size per document                          | 40 KB                                                         |
| Max length for a record ID                                         | 512 characters                                                |
| Max dimensionality for dense vectors                               | 20,000                                                        |
| Max non-zero values for sparse vectors                             | 2048                                                          |
| Max dimensionality for sparse vectors                              | 4.2 billion                                                   |

The 40 KB filterable metadata limit does not apply to `full_text_search` text fields.

### Import limits

<Note>
  If your import exceeds these limits, you'll get an error specifying the limit exceeded. See [Troubleshooting](/guides/index-data/import-data#troubleshooting) for details.
</Note>

| Metric                                        | Limit     |
| :-------------------------------------------- | :-------- |
| Max namespaces per import                     | 10,000    |
| Max total input data size (on-demand indexes) | 1 TB      |
| Max total input data size (DRN indexes)       | Unlimited |
| Max files per import                          | 100,000   |
| Max size per file                             | 10 GB     |

The total input data size limit does not apply to indexes with [dedicated read nodes](/guides/index-data/dedicated-read-nodes).

Bulk import supports indexes without a schema definition (Parquet files) and indexes with document schemas ([JSONL files](/guides/search/full-text-search#bulk-import)). Semantic-text (auto-embedded) fields are not yet supported in document schemas.

### Query limits

| Metric            | Limit  |
| :---------------- | :----- |
| Max `top_k` value | 10,000 |
| Max result size   | 4MB    |

The query result size is affected by the dimension of the dense vectors and whether or not dense vector values and metadata are included in the result.

<Tip>
  If a query fails due to exceeding the 4MB result size limit, choose a lower `top_k` value, or use `include_metadata=False` or `include_values=False` to exclude metadata or values from the result. For better performance, especially with higher `top_k` values, avoid including vector values unless you need them.
</Tip>

### Fetch limits

**Fetch by ID limits:**

| Metric                           | Limit |
| :------------------------------- | :---- |
| Max record IDs per fetch request | 1,000 |

**Fetch by metadata limits:**

| Metric                   | Limit                               |
| :----------------------- | :---------------------------------- |
| Max records per response | 10,000                              |
| Max response size        | 4 MB                                |
| Max request rate         | 5 requests per second per namespace |

To retrieve more than 10,000 matching records, paginate through results using the `paginationToken` parameter. See [Fetch records by metadata](/guides/manage-data/fetch-data#fetch-records-by-metadata).

### Delete limits

| Metric                            | Limit |
| :-------------------------------- | :---- |
| Max record IDs per delete request | 1,000 |

### Metadata filter limits

The following limits apply to [metadata filter expressions](/guides/search/filter-by-metadata#metadata-filter-expressions) used in query, delete, update, and fetch operations.

| Limit                                       | Value  | Description                                                                                                                                                                                                      |
| :------------------------------------------ | :----- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Maximum values per `$in` or `$nin` operator | 10,000 | Each `$in` or `$nin` operator accepts up to 10,000 values in its array. This limit applies per operator—if you have multiple `$in` operators in a single filter, each is independently limited to 10,000 values. |

When you exceed this limit, the request will fail and return a `400 - BAD_REQUEST` error.

#### Rationale

Large `$in` operators can impact query performance and cost. Filters with thousands of values increase request payload size and end-to-end latency. Additionally, using large filters typically indicates a shared namespace architecture, which increases query costs—queries scan the entire namespace regardless of filters.

#### Alternative approaches

If you need to filter by more than 10,000 values, consider these alternatives:

* **Use namespaces for tenant isolation**: Instead of filtering by tenant IDs within a single namespace, create separate namespaces for each tenant or tenant group. This can also reduce query costs. See [Design for multi-tenancy](/guides/index-data/data-modeling#design-for-multi-tenancy).
* **Use broader access control groups**: Instead of filtering by individual user IDs, filter by organization, project, or role. This reduces the number of values in your `$in` filter. See [Design for multi-tenancy](/guides/index-data/data-modeling#use-access-control-groups-instead-of-individual-ids).
* **Post-filter client-side**: Retrieve a larger top K without filtering (for example, top 1000), then filter results client-side.
* **Run multiple queries**: Split your filter into multiple queries with smaller `$in` operators and combine the results client-side.

<Tip>
  To avoid hitting this limit in production, validate the size of your `$in` and `$nin` arrays in your application code before making the request to Pinecone.
</Tip>

## Identifier limits

An identifier is a string of characters used to identify "named" [objects in Pinecone](/guides/get-started/concepts). The following Pinecone objects use strings as identifiers:

| Object                                                    | Field       | Max # characters | Allowed characters                                                                                                                        |
| --------------------------------------------------------- | ----------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| [Organization](/guides/get-started/concepts#organization) | `name`      | 512              | <ul><li>UTF-8 except `\0`</li><li>Cannot be empty</li></ul>                                                                               |
| [Project](/guides/get-started/concepts#project)           | `name`      | 512              | <ul><li>UTF-8 except `\0`</li><li>Cannot be empty</li></ul>                                                                               |
| [Index](/guides/get-started/concepts#index)               | `name`      | 45               | <ul><li>`a-z`, `0-9`, and `-`</li><li>Must be lowercase</li><li>Cannot start or end with `-`</li><li>Cannot be empty</li></ul>            |
| [Namespace](/guides/get-started/concepts#namespace)       | `namespace` | 512              | <ul><li>ASCII except `\0`</li><li>For the default namespace, use `""` (or `"__default__"`, in API versions `2025-04` and later)</li></ul> |
| [Record](/guides/get-started/concepts#record)             | `id`        | 512              | <ul><li>ASCII except `\0`</li><li>Cannot be empty</li></ul>                                                                               |


# Errors
Source: https://docs.pinecone.io/reference/api/errors

Pinecone REST API: Pinecone uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the range.

Pinecone uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the `2xx` range indicate success, codes in the `4xx` range indicate an error that failed given the information provided, and codes in the `5xx` range indicate an error with Pinecone's servers.

For guidance on handling errors in production, see [Error handling](/guides/production/error-handling).

## 200 - OK

The request succeeded.

## 201 - CREATED

The request succeeded and a new resource was created.

## 202 - NO CONTENT

The request succeeded, but there is no content to return.

## 400 - INVALID ARGUMENT

The request failed due to an invalid argument.

## 401 - UNAUTHENTICATED

The request failed due to a missing or invalid [API key](/guides/projects/understanding-projects#api-keys).

## 402 - PAYMENT REQUIRED

The request failed due to delinquent payment or account deactivation for non-payment. See [Account deactivation for non-payment](/guides/organizations/manage-billing/non-payment-account-deactivation).

## 403 - FORBIDDEN

The request failed due to an exceeded [quota](/reference/api/database-limits#object-limits) or [index deletion protection](/guides/manage-data/manage-indexes#configure-deletion-protection).

## 404 - NOT FOUND

The request failed because the resource was not found.

## 409 - ALREADY EXISTS

The request failed because the resource already exists.

## 412 - FAILED PRECONDITIONS

The request failed due to preconditions not being met. |

## 422 - UNPROCESSABLE ENTITY

The request failed because the server was unable to process the contained instructions.

## 429 - TOO MANY REQUESTS

The request was [rate-limited](/reference/api/database-limits#rate-limits). [Implement retry logic with exponential backoff](/guides/production/error-handling#handle-rate-limits-429) to handle this error.

## 500 - UNKNOWN

An internal server error occurred. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) to handle transient errors.

## 502 - BAD GATEWAY

The API gateway received an invalid response from a backend service. This is typically a temporary error. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) to handle transient errors.

## 503 - UNAVAILABLE

The server is currently unavailable. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) to handle transient errors.

## 504 - GATEWAY TIMEOUT

The API gateway did not receive a timely response from the backend server. This can occur due to slow requests or backend processing delays. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) to handle transient errors.


# API reference
Source: https://docs.pinecone.io/reference/api/introduction

Pinecone API reference overview for Database, Inference, and Admin endpoints with supported SDKs including Python, Node.js, Java, and Go.

Pinecone's APIs let you interact programmatically with your Pinecone account.

<Note>
  [SDK versions](/reference/pinecone-sdks#sdk-versions) are pinned to specific API versions.
</Note>

## Database

Use the Database API to store and query records in [Pinecone Database](/guides/get-started/quickstart).

The following Pinecone SDKs support the Database API:

<CardGroup>
  <Card title="CLI" icon="terminal" href="/reference/cli/overview" />

  <Card title="Python SDK" icon="python" href="/reference/sdks/python/overview" />

  <Card title="Node.js SDK" icon="node-js" href="/reference/sdks/node/overview" />

  <Card title="Java SDK" icon="java" href="/reference/sdks/java/overview" />

  <Card title="Go SDK" icon="golang" href="/reference/sdks/go/overview" />
</CardGroup>

## Inference

Use the Inference API to generate vector embeddings and rerank results using [embedding models](/guides/index-data/create-an-index#embedding-models) and [reranking models](/guides/search/rerank-results#reranking-models) hosted on Pinecone's infrastructure.

There are two ways to use the Inference API:

* As a standalone service, through the [Rerank documents](/reference/api/latest/inference/rerank) and [Generate vectors](/reference/api/latest/inference/generate-embeddings) endpoints.
* As an integrated part of database operations, through the [Create an index with integrated embedding](/reference/api/latest/control-plane/create_for_model), [Upsert text](/reference/api/latest/data-plane/upsert_records), and [Search with text](/reference/api/latest/data-plane/search_records) endpoints.

The following Pinecone SDKs support using the Inference API:

<CardGroup>
  <Card title="Python SDK" icon="python" href="/reference/sdks/python/overview" />

  <Card title="Node.js SDK" icon="node-js" href="/reference/sdks/node/overview" />

  <Card title="Java SDK" icon="java" href="/reference/sdks/java/overview" />

  <Card title="Go SDK" icon="golang" href="/reference/sdks/go/overview" />
</CardGroup>


# Known limitations
Source: https://docs.pinecone.io/reference/api/known-limitations

Known limitations and feature restrictions for Pinecone indexes, including upsert consistency, metadata rules, and serverless caveats.

This page describes known limitations and feature restrictions in Pinecone.

## General

* [Upserts](/guides/index-data/upsert-data)
  * Pinecone is eventually consistent, so there can be a slight delay before upserted records are available to query.

    After upserting records, use the [`describe_index_stats`](/reference/api/2024-10/data-plane/describeindexstats) operation to check if the current vector count matches the number of records you expect, although this method may not work for pod-based indexes with multiple replicas.
  * Only indexes using the [dotproduct distance metric](/guides/index-data/indexing-overview#dotproduct) support querying sparse-dense vectors.

    Upserting, updating, and fetching sparse-dense vectors in indexes with a different distance metric will succeed, but querying will return an error.
  * Indexes created before February 22, 2023 do not support sparse vectors.
* [Metadata](/guides/index-data/upsert-data#upsert-with-metadata-filters)
  * Null metadata values aren't supported. Instead of setting a key to `null`, remove the key from the metadata payload.
  * Nested JSON objects are not supported.

## Serverless indexes

Serverless indexes do not support the following features:

* [Filtering index statistics by metadata](/reference/api/2024-10/data-plane/describeindexstats)
* [Private endpoints](/guides/production/configure-private-endpoints)

  * This feature is available on AWS only.


# API versioning
Source: https://docs.pinecone.io/reference/api/versioning

Pinecone REST API: Pinecone's APIs are versioned to ensure that your applications continue to work as expected as the platform evolves.

Pinecone's APIs are versioned to ensure that your applications continue to work as expected as the platform evolves. Versions are named by release date in the format `YYYY-MM`, for example, `2025-10`.

## Release schedule

On a quarterly basis, Pinecone releases a new **stable** API version as well as a **release candidate** of the next stable version.

* **Stable:** Each stable version remains unchanged and supported for a minimum of 12 months. Since stable versions are released every 3 months, this means you have at least 9 months to test and migrate your app to the newest stable version before support for the previous version is removed.

* **Release candidate:** The release candidate gives you insight into the upcoming changes in the next stable version. It is available for approximately 3 months before the release of the stable version and can include new features, improvements, and [breaking changes](#breaking-changes).

Below is an example of Pinecone's release schedule:

<img />

<img />

## Specify an API version

<Warning>
  When using the API directly, it is important to specify an API version in your requests. If you don't, requests default to the oldest supported stable version. Once support for that version ends, your requests will default to the next oldest stable version, which could include breaking changes that require you to update your integration.
</Warning>

To specify an API version, set the `X-Pinecone-Api-Version` header to the version name.

For example, to use the latest stable version (`2026-04`) to describe an index, set the `X-Pinecone-Api-Version` header:

```shell curl theme={null}
PINECONE_API_KEY="YOUR_API_KEY"

curl -i -X GET "https://api.pinecone.io/indexes/movie-recommendations" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2026-04"
```

To use an older version, specify that version instead.

## SDK versions

Official [Pinecone SDKs](/reference/pinecone-sdks) provide convenient access to Pinecone APIs. SDK versions are pinned to specific API versions. When a new API version is released, a new version of the SDK is also released.

For the mapping between SDK and API versions, see [SDK versions](/reference/pinecone-sdks#sdk-versions).

## Breaking changes

Breaking changes are changes that can potentially break your integration with a Pinecone API. Breaking changes include:

* Removing an entire operation
* Removing or renaming a parameter
* Removing or renaming a response field
* Adding a new required parameter
* Making a previously optional parameter required
* Changing the type of a parameter or response field
* Removing enum values
* Adding a new validation rule to an existing parameter
* Changing authentication or authorization requirements

## Non-breaking changes

Non-breaking changes are additive and should not break your integration. Additive changes include:

* Adding an operation
* Adding an optional parameter
* Adding an optional request header
* Adding a response field
* Adding a response header
* Adding enum values

## Get updates

To ensure you always know about upcoming API changes, follow the [Release notes](/release-notes/).


# CLI authentication
Source: https://docs.pinecone.io/reference/cli/authentication

Authenticate the Pinecone CLI using user login, service accounts, or API keys, including auth priority and Admin API access rules.

This document describes how to authenticate the Pinecone CLI to manage your Pinecone resources.

## Authentication methods

| Method                              | Admin API | Control/data plane | Best for                         |
| ----------------------------------- | --------- | ------------------ | -------------------------------- |
| [User login](#user-login)           | ✅         | ✅                  | Interactive use                  |
| [Service account](#service-account) | ✅         | ✅                  | Automation with Admin API access |
| [API key](#api-key)                 | ❌         | ✅                  | Simple automation, CI/CD         |

### User login

Authenticate through a web browser. The token refreshes automatically and stays valid for up to 120 days (re-auth required after 30 days of inactivity).

```bash theme={null}
pc auth login
```

The CLI auto-targets your default organization and its first project. Change with `pc target -o "my-org" -p "my-project"`.

### Service account

Authenticate with credentials from a [service account](/guides/organizations/manage-service-accounts).

```bash theme={null}
pc auth configure --client-id "ID" --client-secret "SECRET"

# Or via environment variables
export PINECONE_CLIENT_ID="your-client-id"
export PINECONE_CLIENT_SECRET="your-client-secret"
```

The CLI auto-targets the service account's organization. For projects: auto-selects if one exists, prompts if multiple exist, or set manually with `pc target -p "my-project"`.

### API key

Authenticate with an [API key](/guides/projects/manage-api-keys). API keys can't access the Admin API.

```bash theme={null}
pc auth configure --api-key "YOUR_API_KEY"

# Or via environment variable
export PINECONE_API_KEY="your-api-key"
```

<Warning>
  API keys are scoped to a specific project. When set, control/data plane operations use the **key's project**, ignoring any [target context](/reference/cli/target-context) you've set.
</Warning>

## Auth priority

When multiple credentials exist, the CLI chooses based on operation type. Within each credential type, environment variables take precedence over stored configuration.

**Control/data plane operations:**

1. API key
2. User login token (via [managed keys](#managed-keys))
3. Service account (via [managed keys](#managed-keys))

**Admin API operations:**

1. User login token
2. Service account

<Note>
  User login and service account are mutually exclusive when configured via CLI commands—each clears the other. However, service account env vars don't clear a stored user login token.
</Note>

**Example scenarios:**

* If `PINECONE_API_KEY` is set, the CLI uses it for control/data plane operations, regardless of any stored API key.
* If you're logged in via `pc auth login` and also have `PINECONE_CLIENT_ID`/`PINECONE_CLIENT_SECRET` set, the user login token is used for everything—the service account env vars are ignored.
* If you have an API key configured and are also logged in, the API key is used for control/data plane operations, but user login is used for Admin API operations (since API keys can't access Admin API).

## Managed keys

When using user login or service account (without a default API key), the CLI automatically creates and manages API keys for control/data plane operations. This happens transparently on first use.

* **Stored locally:** `~/.config/pinecone/secrets.yaml` (permissions 0600)
* **Stored remotely:** Visible in console as `pinecone-cli-{id}` with origin `cli_created`

```bash theme={null}
# List locally tracked managed keys
pc auth local-keys list

# Delete managed keys (local + remote)
pc auth local-keys prune

# Delete only CLI-created managed keys
pc auth local-keys prune --origin cli

# Delete only user-created managed keys
pc auth local-keys prune --origin user

# Delete a specific API key by ID
pc api-key delete --id "KEY_ID"
```

<Note>
  When you run `pc api-key create --store` for a project that already has a CLI-created managed key, the CLI automatically deletes the old remote key before storing the new one.
</Note>

## Logging out

```bash theme={null}
pc auth logout
```

Clears all local auth data: tokens, credentials, API keys, managed keys, and [target context](/reference/cli/target-context).

<Note>
  `pc auth logout` doesn't delete managed keys from Pinecone's servers. Run `pc auth local-keys prune` first for full cleanup.
</Note>

## Local storage

Auth data is stored in `~/.config/pinecone/` with 0600 permissions:

| File           | Contents                                                         |
| -------------- | ---------------------------------------------------------------- |
| `secrets.yaml` | OAuth token, service account credentials, API keys, managed keys |
| `state.yaml`   | Target org/project                                               |
| `config.yaml`  | CLI settings (color, environment)                                |

## Check status

```bash theme={null}
pc auth status
```

Shows your current authentication method, target organization and project, token expiration (for user login), and environment configuration.


# CLI command reference
Source: https://docs.pinecone.io/reference/cli/command-reference

Complete Pinecone CLI command reference covering syntax, subcommands, flags, help output, and exit codes for auth, index, and project.

This document provides a complete reference for all Pinecone CLI commands.

## Command structure

The Pinecone CLI uses a hierarchical command structure. Each command consists of a primary command followed by one or more subcommands and optional flags.

```bash theme={null}
pc <command> <subcommand> [flags]
pc <command> <subcommand> <subcommand> [flags]
```

For example:

```bash theme={null}
# Top-level command with flags
pc target -o "organization-name" -p "project-name"

# Command (index) and subcommand (list)
pc index list

# Command (index) and subcommand (create) with flags
pc index create \
  --name my-index \
  --dimension 1536 \
  --metric cosine \
  --cloud aws \
  --region us-east-1

# Command (auth) and nested subcommands (local-keys prune) with flags
pc auth local-keys prune --id proj-abc123 --skip-confirmation
```

## Getting help

The CLI provides help for commands at every level:

```bash theme={null}
# top-level help
pc --help
pc -h

# command help
pc auth --help
pc index --help
pc project --help

# subcommmand help
pc index create --help
pc project create --help
pc auth configure --help

# nested subcommand help
pc auth local-keys prune --help
```

## Exit codes

All commands return exit code `0` for success and `1` for error.

## Available commands

This section describes all commands offered by the Pinecone CLI.

### Top-level commands

<AccordionGroup>
  <Accordion title="pc login (Authenticate via user login)">
    **Description**

    Authenticate via a web browser. After login, set a [target org and project](/reference/cli/target-context) with `pc target` before accessing data. This command defaults to an initial organization and project to which
    you have access (these values display in the terminal), but you can change them with `pc target`.

    **Usage**

    ```bash theme={null}
    pc login
    ```

    **Flags**

    None

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Log in via browser
    pc login

    # Then set target context
    pc target -o "my-org" -p "my-project"
    ```

    <Note>
      This is an alias for `pc auth login`. Both commands perform the same operation.
    </Note>
  </Accordion>

  <Accordion title="pc logout (Clear credentials / log out)">
    **Description**

    Clears all authentication data from local storage, including:

    * User login token
    * Service account credentials (client ID and secret)
    * Default (manually specified) API key
    * Locally managed keys (for all projects)
    * Target organization and project context

    **Usage**

    ```bash theme={null}
    pc logout
    ```

    **Flags**

    None

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Clear all credentials and context
    pc logout
    ```

    <Note>
      This is an alias for `pc auth logout`. Both commands perform the same operation. Does not delete managed API keys from Pinecone's servers. Run `pc auth local-keys prune` before logging out to fully clean up.
    </Note>
  </Accordion>

  <Accordion title="pc target (Set target organization and project)">
    **Description**

    Set the target organization and project for the CLI. Supports interactive organization and project selection or direct specification via flags.  For details, see [CLI target context](/reference/cli/target-context).

    **Usage**

    ```bash theme={null}
    pc target [flags]
    ```

    **Flags**

    | Long flag           | Short flag | Description                    |
    | :------------------ | :--------- | :----------------------------- |
    | `--clear`           |            | Clear target context           |
    | `--json`            | `-j`       | Output in JSON format          |
    | `--org`             | `-o`       | Organization name              |
    | `--organization-id` |            | Organization ID                |
    | `--project`         | `-p`       | Project name                   |
    | `--project-id`      |            | Project ID                     |
    | `--show`            | `-s`       | Display current target context |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Interactive targeting after login
    pc login
    pc target

    # Set specific organization and project
    pc target -o "my-org" -p "my-project"

    # Show current context
    pc target --show

    # Clear all context
    pc target --clear
    ```
  </Accordion>

  <Accordion title="pc version (Show CLI version)">
    **Description**

    Displays version information for the CLI, including the version number, commit SHA, and build date.

    **Usage**

    ```bash theme={null}
    pc version
    ```

    **Flags**

    None

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Display version information
    pc version
    ```
  </Accordion>

  <Accordion title="pc whoami (Show current user)">
    **Description**

    Displays information about the currently authenticated user. To use this command, you must be authenticated via user login.

    **Usage**

    ```bash theme={null}
    pc whoami
    ```

    **Flags**

    None

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    pc whoami
    ```

    <Note>
      This is an alias for `pc auth whoami`. Both commands perform the same operation.
    </Note>
  </Accordion>
</AccordionGroup>

### Authentication

<AccordionGroup>
  <Accordion title="pc auth clear (Clear specific credentials)">
    **Description**

    Selectively clears specific authentication data without affecting other credentials. At least one flag is required.

    **Usage**

    ```bash theme={null}
    pc auth clear [flags]
    ```

    **Flags**

    | Long flag           | Short flag | Description                                         |
    | :------------------ | :--------- | :-------------------------------------------------- |
    | `--api-key`         |            | Clear only the default (manually specified) API key |
    | `--service-account` |            | Clear only service account credentials              |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Clear only the default (manually specified) API key
    pc auth clear --api-key
    pc auth status

    # Clear service account
    pc auth clear --service-account
    ```

    <Note>
      More surgical than `pc auth logout`. Does not clear user login token or managed keys. For those, use `pc auth logout` or `pc auth local-keys prune`.
    </Note>
  </Accordion>

  <Accordion title="pc auth configure (Configure service account or API key)">
    **Description**

    Configures service account credentials or a default (manually specified) API key.

    Service accounts automatically target the organization and prompt for project selection, unless there is only one project. A default API key overrides any previously specified target organization/project context. When setting a service account, this operation clears the user login token, if one exists.
    For details, see [CLI target context](/reference/cli/target-context).

    **Usage**

    ```bash theme={null}
    pc auth configure [flags]
    ```

    **Flags**

    | Long flag               | Short flag | Description                                          |
    | :---------------------- | :--------- | :--------------------------------------------------- |
    | `--api-key`             |            | Default API key to use for authentication            |
    | `--client-id`           |            | Service account client ID                            |
    | `--client-secret`       |            | Service account client secret                        |
    | `--client-secret-stdin` |            | Read client secret from stdin                        |
    | `--json`                | `-j`       | Output in JSON format                                |
    | `--project-id`          | `-p`       | Target project ID (optional, interactive if omitted) |
    | `--prompt-if-missing`   |            | Prompt for missing credentials                       |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Service account setup (auto-targets org and prompts for project)
    pc auth configure --client-id my-id --client-secret my-secret

    # Service account with specific project
    pc auth configure \
      --client-id my-id \
      --client-secret my-secret \
      -p proj-123

    # Default API key (overrides any target context)
    pc auth configure --api-key pcsk_abc123
    ```

    <Note>
      `pc auth configure --api-key "YOUR_API_KEY"` does the same thing as `pc config set-api-key "YOUR_API_KEY"`. To learn about targeting a project after authenticating with a service account, see [CLI target context](/reference/cli/target-context).
    </Note>
  </Accordion>

  <Accordion title="pc auth local-keys list (List managed keys)">
    **Description**

    Displays all [managed API keys](/reference/cli/authentication#managed-keys) stored locally by the CLI, with various details.

    **Usage**

    ```bash theme={null}
    pc auth local-keys list [flags]
    ```

    **Flags**

    | Long flag  | Short flag | Description                                |
    | :--------- | :--------- | :----------------------------------------- |
    | `--json`   | `-j`       | Output in JSON format                      |
    | `--reveal` |            | Show the actual API key values (sensitive) |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # List all locally managed keys
    pc auth local-keys list

    # Show key values
    pc auth local-keys list --reveal

    # After storing a key
    pc api-key create -n "my-key" --store
    pc auth local-keys list
    ```
  </Accordion>

  <Accordion title="pc auth local-keys prune (Delete managed keys)">
    **Description**

    Deletes locally stored [managed API keys](/reference/cli/authentication#managed-keys) from local storage and Pinecone's servers. Filters by origin (`cli`/`user`/`all`) or project ID.

    **Usage**

    ```bash theme={null}
    pc auth local-keys prune [flags]
    ```

    **Flags**

    | Long flag             | Short flag | Description                                                 |
    | :-------------------- | :--------- | :---------------------------------------------------------- |
    | `--dry-run`           |            | Preview deletions without applying                          |
    | `--id`                |            | Prune keys for specific project ID only                     |
    | `--json`              | `-j`       | Output in JSON format                                       |
    | `--origin`            | `-o`       | Filter by origin - `cli`, `user`, or `all` (default: `all`) |
    | `--skip-confirmation` |            | Skip confirmation prompt                                    |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Preview deletions
    pc auth local-keys prune --dry-run

    # Delete CLI-created keys only
    pc auth local-keys prune -o cli --skip-confirmation

    # Delete for specific project
    pc auth local-keys prune --id proj-abc123

    # Before/after check
    pc auth local-keys list
    pc auth local-keys prune -o cli
    pc auth local-keys list
    ```

    <Note>
      This deletes keys from both local storage and Pinecone servers. Use `--dry-run` to preview before committing.
    </Note>
  </Accordion>

  <Accordion title="pc auth login (Authenticate via user login)">
    **Description**

    Authenticate via user login in the web browser. After login, [set a target org and project](/reference/cli/target-context).

    **Usage**

    ```bash theme={null}
    pc auth login
    pc login  # shorthand
    ```

    **Flags**

    None

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Login and set target
    pc auth login
    pc target -o "my-org" -p "my-project"
    pc index list
    ```

    <Note>
      Tokens refresh automatically and remain valid for up to 120 days. If you're inactive for more than 30 days, you must re-authenticate. Logging in clears any existing service account credentials. This command does the same thing as `pc login`.
    </Note>
  </Accordion>

  <Accordion title="pc auth logout (Clear authentication credentials)">
    **Description**

    Clears all authentication data from local storage, including:

    * User login token
    * Service account credentials (client ID and secret)
    * Default (manually specified) API key
    * Locally managed keys (for all projects)
    * Target organization and project context

    **Usage**

    ```bash theme={null}
    pc auth logout
    ```

    **Flags**

    None

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Clear all credentials and context
    pc auth logout
    ```

    <Note>
      This command does the same thing as `pc logout`. Does not delete managed API keys from Pinecone's servers. Run `pc auth local-keys prune` before logging out to fully clean up.
    </Note>
  </Accordion>

  <Accordion title="pc auth status (Show authentication status)">
    **Description**

    Shows details about all configured authentication methods.

    **Usage**

    ```bash theme={null}
    pc auth status [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description           |
    | :-------- | :--------- | :-------------------- |
    | `--json`  | `-j`       | Output in JSON format |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Check status after login
    pc auth login
    pc auth status

    # JSON output for scripting
    pc auth status --json
    ```
  </Accordion>

  <Accordion title="pc auth whoami (Show current user information)">
    **Description**

    Displays information about the currently authenticated user. To use this command, you must be authenticated via user login.

    **Usage**

    ```bash theme={null}
    pc auth whoami
    ```

    **Flags**

    None

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    pc auth whoami
    ```

    <Note>
      This command does the same thing as `pc whoami`.
    </Note>
  </Accordion>
</AccordionGroup>

### Indexes

<AccordionGroup>
  <Accordion title="pc index configure (Update index configuration)">
    **Description**

    Modifies the configuration of an existing index.

    **Usage**

    ```bash theme={null}
    pc index configure [flags]
    ```

    **Flags**

    | Long flag                | Short flag | Description                                                     |
    | :----------------------- | :--------- | :-------------------------------------------------------------- |
    | `--index-name`           | `-i`       | Name of index to configure (required)                           |
    | `--deletion-protection`  |            | Enable or disable deletion protection - `enabled` or `disabled` |
    | `--tags`                 |            | Custom user tags (key=value pairs)                              |
    | `--json`                 | `-j`       | Output in JSON format                                           |
    | **Dedicated read nodes** |            |                                                                 |
    | `--read-mode`            |            | Read capacity mode - `ondemand` or `dedicated`                  |
    | `--read-node-type`       |            | Node type for dedicated read - `b1` or `t1`                     |
    | `--read-shards`          |            | Number of shards for dedicated read capacity                    |
    | `--read-replicas`        |            | Number of replicas for dedicated read capacity                  |
    | **Integrated embedding** |            |                                                                 |
    | `--model`                |            | Embedding model name                                            |
    | `--field-map`            |            | Field mapping for embedding (key=value pairs)                   |
    | `--read-parameters`      |            | Read parameters for embedding model (key=value pairs)           |
    | `--write-parameters`     |            | Write parameters for embedding model (key=value pairs)          |
    | **Pods**                 |            |                                                                 |
    | `--pod-type`             | `-t`       | Type of pod to use; can only upgrade when configuring           |
    | `--replicas`             | `-r`       | Number of replicas of the index to configure                    |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Enable deletion protection
    pc index configure --index-name my-index --deletion-protection enabled

    # Add tags
    pc index configure --index-name my-index --tags environment=production,team=ml

    # Switch to dedicated read capacity
    pc index configure --index-name my-index \
      --read-mode dedicated \
      --read-node-type b1 \
      --read-shards 2 \
      --read-replicas 2

    # Verify changes
    pc index describe --index-name my-index
    ```

    <Note>
      Configuration changes may take some time to take effect.
    </Note>
  </Accordion>

  <Accordion title="pc index create (Create a new index)">
    **Description**

    Creates a new index in your Pinecone project. Supports serverless, pod-based, integrated (with embedding model), and BYOC (Bring Your Own Cloud) index types.

    **Usage**

    ```bash theme={null}
    pc index create [flags]
    ```

    **Flags**

    | Long flag                | Short flag | Description                                                                    |
    | :----------------------- | :--------- | :----------------------------------------------------------------------------- |
    | `--name`                 | `-n`       | Index name (required)                                                          |
    | `--dimension`            | `-d`       | Vector dimension (required for standard indexes, optional for integrated)      |
    | `--metric`               | `-m`       | Similarity metric - `cosine`, `euclidean`, or `dotproduct` (default: `cosine`) |
    | `--cloud`                | `-c`       | Cloud provider - `aws`, `gcp`, or `azure`                                      |
    | `--region`               | `-r`       | Cloud region                                                                   |
    | `--vector-type`          | `-v`       | Vector type - `dense` or `sparse` (serverless only)                            |
    | `--source-collection`    |            | Name of the source collection from which to create the index                   |
    | `--schema`               |            | Metadata schema to control which fields are indexed (comma-separated)          |
    | `--deletion-protection`  |            | Deletion protection - `enabled` or `disabled`                                  |
    | `--tags`                 |            | Custom user tags (key=value pairs)                                             |
    | `--json`                 | `-j`       | Output in JSON format                                                          |
    | **Integrated indexes**   |            |                                                                                |
    | `--model`                |            | Integrated embedding model name                                                |
    | `--field-map`            |            | Field mapping for integrated embedding (key=value pairs)                       |
    | `--read-parameters`      |            | Read parameters for embedding model (key=value pairs)                          |
    | `--write-parameters`     |            | Write parameters for embedding model (key=value pairs)                         |
    | **BYOC indexes**         |            |                                                                                |
    | `--byoc-environment`     |            | BYOC environment to use for the index                                          |
    | **Dedicated read nodes** |            |                                                                                |
    | `--read-mode`            |            | Read capacity mode - `ondemand` or `dedicated` (default: `ondemand`)           |
    | `--read-node-type`       |            | Node type for dedicated read - `b1` or `t1`                                    |
    | `--read-shards`          |            | Number of shards (each shard provides 250 GB storage)                          |
    | `--read-replicas`        |            | Number of replicas for higher throughput                                       |
    | **Pod-based indexes**    |            |                                                                                |
    | `--environment`          |            | Environment of the index to create (for example, `us-east-1-aws`)              |
    | `--pod-type`             |            | Type of pod to use (for example, `p1.x1`, `s1.x2`)                             |
    | `--shards`               |            | Number of shards (default: `1`)                                                |
    | `--replicas`             |            | Number of replicas (default: `1`)                                              |
    | `--metadata-config`      |            | Comma-separated list of metadata fields to index for search                    |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Create serverless index
    pc index create -n my-index -d 1536 -m cosine -c aws -r us-east-1

    # Create sparse vector index
    pc index create -n sparse-index -m dotproduct -c aws -r us-east-1 --vector-type sparse

    # With integrated embedding model
    pc index create \
      -n my-index \
      -m cosine \
      -c aws \
      -r us-east-1 \
      --model multilingual-e5-large \
      --field-map text=chunk_text

    # With dedicated read capacity
    pc index create \
      -n my-index \
      -d 1536 \
      -m cosine \
      -c aws \
      -r us-east-1 \
      --read-mode dedicated \
      --read-node-type b1 \
      --read-shards 2 \
      --read-replicas 2

    # With deletion protection
    pc index create \
      -n my-index \
      -d 1536 \
      -m cosine \
      -c aws \
      -r us-west-2 \
      --deletion-protection enabled

    # From collection
    pc index create \
      -n my-index \
      -d 1536 \
      -m cosine \
      -c aws \
      -r eu-west-1 \
      --source-collection my-collection

    # Create pod-based index
    pc index create \
      -n my-index \
      -d 1536 \
      -m cosine \
      --environment us-east-1-aws \
      --pod-type p1.x1 \
      --shards 1 \
      --replicas 1
    ```

    <Note>
      For a list of valid regions for a serverless index, see [Create a serverless index](/guides/index-data/create-an-index).
    </Note>
  </Accordion>

  <Accordion title="pc index delete (Delete an index)">
    **Description**

    Permanently deletes an index and all its data. This operation cannot be undone.

    **Usage**

    ```bash theme={null}
    pc index delete [flags]
    ```

    **Flags**

    | Long flag             | Short flag | Description                                                |
    | :-------------------- | :--------- | :--------------------------------------------------------- |
    | `--index-name`        | `-i`       | Name of index to delete (required)                         |
    | `--skip-confirmation` |            | Skip the deletion confirmation prompt                      |
    | `--json`              | `-j`       | Output in JSON format (also skips the confirmation prompt) |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Delete an index (prompts for confirmation)
    pc index delete --index-name my-index

    # Skip the confirmation prompt
    pc index delete --index-name my-index --skip-confirmation

    # List before and after
    pc index list
    pc index delete --index-name test-index --skip-confirmation
    pc index list
    ```

    <Note>
      This command prompts for confirmation before deleting. Pass `--skip-confirmation` (or `--json`) to bypass the prompt in non-interactive contexts.
    </Note>
  </Accordion>

  <Accordion title="pc index describe (Show index details)">
    **Description**

    Displays detailed configuration and status information for a specific index.

    **Usage**

    ```bash theme={null}
    pc index describe [flags]
    ```

    **Flags**

    | Long flag      | Short flag | Description           |
    | :------------- | :--------- | :-------------------- |
    | `--index-name` | `-i`       | Index name (required) |
    | `--json`       | `-j`       | Output in JSON format |

    The `--name`/`-n` flag is a deprecated alias for `--index-name`/`-i`.

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Describe an index
    pc index describe -i my-index

    # JSON output
    pc index describe -i my-index -j

    # Check newly created index
    pc index create -n test-index -d 1536 -m cosine -c aws -r us-east-1
    pc index describe -i test-index
    ```
  </Accordion>

  <Accordion title="pc index stats (Show index statistics)">
    **Description**

    Displays statistics for an index, including total vector count and namespace breakdown. Optionally filter results with a metadata filter.

    **Usage**

    ```bash theme={null}
    pc index stats [flags]
    ```

    **Flags**

    | Long flag      | Short flag | Description                                                    |
    | :------------- | :--------- | :------------------------------------------------------------- |
    | `--index-name` | `-i`       | Index name (required)                                          |
    | `--filter`     | `-f`       | Metadata filter (inline JSON, `./path.json`, or `-` for stdin) |
    | `--json`       | `-j`       | Output in JSON format                                          |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Get stats for an index
    pc index stats -i my-index

    # Get stats with a metadata filter
    pc index stats -i my-index --filter '{"genre":{"$eq":"rock"}}'

    # Filter from file
    pc index stats -i my-index --filter ./filter.json

    # JSON output
    pc index stats -i my-index -j
    ```
  </Accordion>

  <Accordion title="pc index list (List all indexes)">
    **Description**

    Displays all indexes in your current target project, including various details.

    **Usage**

    ```bash theme={null}
    pc index list [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description                                         |
    | :-------- | :--------- | :-------------------------------------------------- |
    | `--json`  | `-j`       | Output in JSON format (includes full index details) |
    | `--wide`  | `-w`       | Show additional columns (host, embed, tags)         |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # List all indexes
    pc index list

    # Show additional details
    pc index list --wide

    # JSON output for scripting
    pc index list -j

    # After creating indexes
    pc index create -n test-1 -d 768 -m cosine -c aws -r us-east-1
    pc index list
    ```
  </Accordion>
</AccordionGroup>

### Namespaces

<AccordionGroup>
  <Accordion title="pc index namespace create (Create a namespace)">
    **Description**

    Creates a new namespace within an index. Namespaces allow you to partition vectors within an index.

    **Usage**

    ```bash theme={null}
    pc index namespace create [flags]
    ```

    **Flags**

    | Long flag      | Short flag | Description                                         |
    | :------------- | :--------- | :-------------------------------------------------- |
    | `--index-name` | `-i`       | Index name (required)                               |
    | `--name`       |            | Namespace name (required)                           |
    | `--schema`     |            | Metadata schema for the namespace (comma-separated) |
    | `--json`       | `-j`       | Output in JSON format                               |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Create a namespace
    pc index namespace create -i my-index --name tenant-a

    # Create with metadata schema (comma-separated list of filterable metadata fields)
    pc index namespace create -i my-index --name tenant-b --schema "category,brand"

    # JSON output
    pc index namespace create -i my-index --name tenant-c -j
    ```
  </Accordion>

  <Accordion title="pc index namespace delete (Delete a namespace)">
    **Description**

    Deletes a namespace and all its vectors from an index. This operation cannot be undone.

    **Usage**

    ```bash theme={null}
    pc index namespace delete [flags]
    ```

    **Flags**

    | Long flag             | Short flag | Description                                                            |
    | :-------------------- | :--------- | :--------------------------------------------------------------------- |
    | `--index-name`        | `-i`       | Index name (required)                                                  |
    | `--name`              |            | Namespace name (required); use `__default__` for the default namespace |
    | `--skip-confirmation` |            | Skip the deletion confirmation prompt                                  |
    | `--json`              | `-j`       | Output in JSON format (also skips the confirmation prompt)             |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Delete a namespace (prompts for confirmation)
    pc index namespace delete -i my-index --name tenant-a

    # Delete the default namespace
    pc index namespace delete -i my-index --name __default__

    # Skip the confirmation prompt
    pc index namespace delete -i my-index --name tenant-a --skip-confirmation
    ```

    <Warning>
      Deleting a namespace removes all vectors in that namespace. This operation cannot be undone.
    </Warning>
  </Accordion>

  <Accordion title="pc index namespace describe (Show namespace details)">
    **Description**

    Displays detailed information about a specific namespace, including record count and schema configuration.

    **Usage**

    ```bash theme={null}
    pc index namespace describe [flags]
    ```

    **Flags**

    | Long flag      | Short flag | Description                                                            |
    | :------------- | :--------- | :--------------------------------------------------------------------- |
    | `--index-name` | `-i`       | Index name (required)                                                  |
    | `--name`       |            | Namespace name (required); use `__default__` for the default namespace |
    | `--json`       | `-j`       | Output in JSON format                                                  |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Describe a namespace
    pc index namespace describe -i my-index --name tenant-a

    # Describe the default namespace
    pc index namespace describe -i my-index --name __default__

    # JSON output
    pc index namespace describe -i my-index --name tenant-a -j
    ```
  </Accordion>

  <Accordion title="pc index namespace list (List namespaces)">
    **Description**

    Lists all namespaces within an index, including vector counts.

    **Usage**

    ```bash theme={null}
    pc index namespace list [flags]
    ```

    **Flags**

    | Long flag            | Short flag | Description                    |
    | :------------------- | :--------- | :----------------------------- |
    | `--index-name`       | `-i`       | Index name (required)          |
    | `--limit`            | `-l`       | Maximum number of results      |
    | `--pagination-token` | `-p`       | Pagination token for next page |
    | `--prefix`           |            | Filter namespaces by prefix    |
    | `--json`             | `-j`       | Output in JSON format          |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # List all namespaces
    pc index namespace list -i my-index

    # Filter by prefix
    pc index namespace list -i my-index --prefix "tenant-"

    # Limit results
    pc index namespace list -i my-index --limit 10

    # JSON output
    pc index namespace list -i my-index -j
    ```
  </Accordion>
</AccordionGroup>

### Vectors

<AccordionGroup>
  <Accordion title="pc index vector delete (Delete vectors)">
    **Description**

    Deletes vectors from an index by ID, filter, or deletes all vectors in a namespace.

    **Usage**

    ```bash theme={null}
    pc index vector delete [flags]
    ```

    **Flags**

    | Long flag             | Short flag | Description                                                               |
    | :-------------------- | :--------- | :------------------------------------------------------------------------ |
    | `--index-name`        | `-i`       | Index name (required)                                                     |
    | `--namespace`         |            | Namespace to delete from (default: `__default__`)                         |
    | `--ids`               |            | Vector IDs to delete (inline JSON array, `./path.json`, or `-` for stdin) |
    | `--filter`            |            | Metadata filter (inline JSON, `./path.json`, or `-` for stdin)            |
    | `--all-vectors`       |            | Delete all vectors in the namespace                                       |
    | `--skip-confirmation` |            | Skip the confirmation prompt shown for `--all-vectors`                    |
    | `--json`              | `-j`       | Output in JSON format (also skips the confirmation prompt)                |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Delete specific vectors
    pc index vector delete -i my-index --ids '["id1"]'

    # Delete multiple vectors (inline JSON array, or JSON array in a file)
    pc index vector delete -i my-index --ids '["id1", "id2"]'

    # Delete by filter
    pc index vector delete -i my-index --filter '{"genre":"classical"}'

    # Delete all vectors in a namespace (prompts for confirmation)
    pc index vector delete -i my-index --namespace old-data --all-vectors

    # Delete all vectors without the prompt
    pc index vector delete -i my-index --namespace old-data --all-vectors --skip-confirmation
    ```

    <Note>
      Only `--all-vectors` prompts for confirmation. Targeted deletes with `--ids` or `--filter` proceed without a prompt. Pass `--skip-confirmation` (or `--json`) to bypass the `--all-vectors` prompt.
    </Note>

    <Warning>
      Vector deletion is permanent and cannot be undone.
    </Warning>
  </Accordion>

  <Accordion title="pc index vector fetch (Fetch vectors by ID or filter)">
    **Description**

    Retrieves vectors by their IDs or by a metadata filter, returning the vector values and metadata.

    **Usage**

    ```bash theme={null}
    pc index vector fetch [flags]
    ```

    **Flags**

    | Long flag            | Short flag | Description                                                              |
    | :------------------- | :--------- | :----------------------------------------------------------------------- |
    | `--index-name`       | `-i`       | Index name (required)                                                    |
    | `--namespace`        |            | Namespace to fetch from (default: `__default__`)                         |
    | `--ids`              |            | Vector IDs to fetch (inline JSON array, `./path.json`, or `-` for stdin) |
    | `--filter`           | `-f`       | Metadata filter (inline JSON, `./path.json`, or `-` for stdin)           |
    | `--limit`            | `-l`       | Maximum number of vectors to fetch                                       |
    | `--pagination-token` | `-p`       | Pagination token for next page                                           |
    | `--body`             |            | Request body JSON (inline, `./path.json`, or `-` for stdin)              |
    | `--json`             | `-j`       | Output in JSON format                                                    |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Fetch specific vectors by ID
    pc index vector fetch -i my-index --ids '["123","456","789"]'

    # Fetch from a file
    pc index vector fetch -i my-index --ids ./ids.json

    # Fetch by metadata filter
    pc index vector fetch -i my-index --filter '{"genre":{"$eq":"rock"}}'

    # Fetch from a namespace
    pc index vector fetch -i my-index --namespace tenant-a --ids '["doc-123"]'

    # JSON output
    pc index vector fetch -i my-index --ids '["vec1"]' -j
    ```

    <Note>
      Use either `--ids` or `--filter`, not both. When using `--ids`, pagination flags are not applicable.
    </Note>
  </Accordion>

  <Accordion title="pc index vector list (List vector IDs)">
    **Description**

    Lists vector IDs in a namespace with optional pagination.

    **Usage**

    ```bash theme={null}
    pc index vector list [flags]
    ```

    **Flags**

    | Long flag            | Short flag | Description                                     |
    | :------------------- | :--------- | :---------------------------------------------- |
    | `--index-name`       | `-i`       | Index name (required)                           |
    | `--namespace`        |            | Namespace to list from (default: `__default__`) |
    | `--limit`            | `-l`       | Maximum number of IDs to return                 |
    | `--pagination-token` | `-p`       | Pagination token for next page                  |
    | `--json`             | `-j`       | Output in JSON format                           |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # List vector IDs
    pc index vector list -i my-index

    # List from a namespace with limit
    pc index vector list -i my-index --namespace tenant-a --limit 50

    # JSON output
    pc index vector list -i my-index -j
    ```
  </Accordion>

  <Accordion title="pc index vector query (Query vectors)">
    **Description**

    Queries an index for similar vectors using dense vectors, sparse vectors, or vector ID.

    **Usage**

    ```bash theme={null}
    pc index vector query [flags]
    ```

    **Flags**

    | Long flag            | Short flag | Description                                                                       |
    | :------------------- | :--------- | :-------------------------------------------------------------------------------- |
    | `--index-name`       | `-i`       | Index name (required)                                                             |
    | `--namespace`        |            | Namespace to query (default: `__default__`)                                       |
    | `--id`               |            | Query by vector ID                                                                |
    | `--vector`           | `-v`       | Query vector values (inline JSON array, `./path.json`, or `-` for stdin)          |
    | `--sparse-indices`   |            | Sparse vector indices (inline JSON uint32 array, `./path.json`, or `-` for stdin) |
    | `--sparse-values`    |            | Sparse vector values (inline JSON array, `./path.json`, or `-` for stdin)         |
    | `--top-k`            | `-k`       | Number of results to return (default: 10)                                         |
    | `--filter`           | `-f`       | Metadata filter (inline JSON, `./path.json`, or `-` for stdin)                    |
    | `--include-values`   |            | Include vector values in results                                                  |
    | `--include-metadata` |            | Include metadata in results                                                       |
    | `--body`             |            | Request body JSON (inline, `./path.json`, or `-` for stdin)                       |
    | `--json`             | `-j`       | Output in JSON format                                                             |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Query by vector ID
    pc index vector query -i my-index --id "doc-123" -k 10 --include-metadata

    # Query by vector values
    pc index vector query -i my-index --vector '[0.1, 0.2, 0.3]' -k 25

    # Query with metadata filter
    pc index vector query -i my-index \
      --vector '[0.1, 0.2, 0.3]' \
      --filter '{"genre":{"$eq":"sci-fi"}}' \
      --include-metadata

    # Query from file (file contains a JSON array that specifies the query vector)
    pc index vector query -i my-index --vector ./embedding.json -k 20

    # Query with sparse vectors (inline)
    pc index vector query -i my-index \
      --sparse-indices '[0, 5, 12]' \
      --sparse-values '[0.5, 0.3, 0.8]' \
      -k 15

    # Query with sparse vectors from files
    # indices.json: [0, 5, 12]
    # values.json: [0.5, 0.3, 0.8]
    pc index vector query -i my-index \
      --sparse-indices ./indices.json \
      --sparse-values ./values.json \
      -k 15

    # Query from stdin (extract embedding from a document)
    # doc.json: {"id": "doc-123", "embedding": [0.1, 0.2, 0.3], "text": "..."}
    jq -c '.embedding' doc.json | pc index vector query -i my-index --vector - -k 10
    ```

    <Note>
      Use `--id`, `--vector`, or sparse vectors (`--sparse-indices` and `--sparse-values`) to specify what to query against. These options are mutually exclusive.
    </Note>
  </Accordion>

  <Accordion title="pc index vector update (Update vectors)">
    **Description**

    Updates a vector's values, sparse values, or metadata by ID, or updates metadata for multiple vectors matching a filter.

    **Usage**

    ```bash theme={null}
    pc index vector update [flags]
    ```

    **Flags**

    | Long flag          | Short flag | Description                                                                    |
    | :----------------- | :--------- | :----------------------------------------------------------------------------- |
    | `--index-name`     | `-i`       | Index name (required)                                                          |
    | `--namespace`      |            | Namespace containing the vector (default: `__default__`)                       |
    | `--id`             |            | Vector ID to update                                                            |
    | `--values`         |            | New vector values (inline JSON array, `./path.json`, or `-` for stdin)         |
    | `--sparse-indices` |            | New sparse indices (inline JSON uint32 array, `./path.json`, or `-` for stdin) |
    | `--sparse-values`  |            | New sparse values (inline JSON array, `./path.json`, or `-` for stdin)         |
    | `--metadata`       |            | New or updated metadata (inline JSON, `./path.json`, or `-` for stdin)         |
    | `--filter`         |            | Metadata filter for bulk update (inline JSON, `./path.json`, or `-` for stdin) |
    | `--dry-run`        |            | Preview how many records would be updated without applying changes             |
    | `--body`           |            | Request body JSON (inline, `./path.json`, or `-` for stdin)                    |
    | `--json`           | `-j`       | Output in JSON format                                                          |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Update metadata for a single vector
    pc index vector update -i my-index --id "vec1" --metadata '{"category":"updated"}'

    # Update values for a single vector
    pc index vector update -i my-index --id "vec1" --values '[0.2, 0.3, 0.4]'

    # Update sparse values
    # indices.json: [0, 5, 12]
    # values.json: [0.5, 0.3, 0.8]
    pc index vector update -i my-index --id "vec1" \
      --sparse-indices ./indices.json \
      --sparse-values ./values.json

    # Bulk update metadata by filter (preview first)
    pc index vector update -i my-index \
      --filter '{"genre":{"$eq":"sci-fi"}}' \
      --metadata '{"genre":"fantasy"}' \
      --dry-run

    # Apply the bulk update
    pc index vector update -i my-index \
      --filter '{"genre":{"$eq":"sci-fi"}}' \
      --metadata '{"genre":"fantasy"}'
    ```

    <Note>
      Use either `--id` for single vector updates or `--filter` for bulk updates. These options are mutually exclusive.
    </Note>
  </Accordion>

  <Accordion title="pc index vector upsert (Upsert vectors)">
    **Description**

    Inserts or updates vectors in an index from a JSON or JSONL file, or inline JSON. The CLI automatically batches vectors for efficient uploading. Files can contain any number of vectors—the CLI splits them into batches and sends multiple API requests as needed.

    **Usage**

    ```bash theme={null}
    pc index vector upsert [flags]
    ```

    **Flags**

    | Long flag      | Short flag | Description                                                                        |
    | :------------- | :--------- | :--------------------------------------------------------------------------------- |
    | `--index-name` | `-i`       | Index name (required)                                                              |
    | `--namespace`  |            | Namespace to upsert into (default: `__default__`)                                  |
    | `--body`       |            | Request body JSON or JSONL (inline, `./path.json[l]`, or `-` for stdin) (required) |
    | `--batch-size` | `-b`       | Size of batches to upsert (default: 500)                                           |
    | `--json`       | `-j`       | Output in JSON format                                                              |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Upsert from JSON file (with "vectors" array)
    # vectors.json: {"vectors": [{"id": "vec1", "values": [0.1, 0.2, 0.3], "metadata": {"genre": "comedy"}}]}
    pc index vector upsert -i my-index --body ./vectors.json

    # Upsert with inline JSON
    pc index vector upsert -i my-index --body '{"vectors": [{"id": "vec1", "values": [0.1, 0.2, 0.3], "metadata": {"genre": "comedy"}}]}'

    # Upsert from JSONL file (one vector per line)
    # vectors.jsonl: {"id": "vec1", "values": [0.1, 0.2, 0.3]}
    #                {"id": "vec2", "values": [0.4, 0.5, 0.6]}
    pc index vector upsert -i my-index --body ./vectors.jsonl

    # Upsert from stdin (same format as JSON or JSONL file)
    cat vectors.json | pc index vector upsert -i my-index --body -

    # Custom batch size (default: 500, max: 1000 per API request)
    pc index vector upsert -i my-index --body ./vectors.json --batch-size 1000
    ```

    <Note>
      **Batch size limits:** The API accepts up to 1000 vectors per request. The CLI defaults to batches of 500 vectors, but you can adjust this with `--batch-size` (up to 1000). Large files are automatically split into multiple batches.

      **File size:** There's no explicit file size limit—the CLI reads the entire file into memory and batches it automatically. Very large files are supported as long as they fit in available system memory.
    </Note>
  </Accordion>
</AccordionGroup>

### Records

<AccordionGroup>
  <Accordion title="pc index record search (Search records in an index)">
    **Description**

    Search an index namespace with a query text, query vector, or record ID and return the most similar records, along with their similarity scores. Optionally, rerank the initial results based on their relevance to the query.

    Searching with text is supported only for indexes with an integrated embedding configured. Searching with a query vector or record ID is supported for all indexes.

    Exactly one primary query mode must be provided:

    * `--inputs` — query text (requires an index with integrated embedding)
    * `--id` — use an existing record's vector as the query
    * `--vector` — provide a dense vector directly (all index types)
    * `--sparse-indices` + `--sparse-values` — sparse vector (all index types)

    Combine `--vector` with `--sparse-indices`/`--sparse-values` for hybrid search. Use `--body` to pass a full request object; flags take precedence over `--body` when both specify the same field.

    **Usage**

    ```bash theme={null}
    pc index record search [flags]
    ```

    **Flags**

    | Long flag          | Short flag | Description                                                                                                                                                     |
    | :----------------- | :--------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `--index-name`     | `-i`       | Name of the index to search (required)                                                                                                                          |
    | `--inputs`         |            | Query inputs for text search (inline JSON, `./path.json`, or `-` for stdin); requires integrated embedding. Mutually exclusive with `--id` and `--vector`.      |
    | `--id`             |            | Use an existing record's vector by ID for the query. Mutually exclusive with `--inputs` and `--vector`.                                                         |
    | `--vector`         | `-v`       | Dense vector values to search against (inline JSON float32 array, `./path.json`, or `-` for stdin). Mutually exclusive with `--inputs` and `--id`.              |
    | `--sparse-indices` |            | Sparse vector indices (inline JSON int32 array, `./path.json`, or `-` for stdin). Must be used together with `--sparse-values`.                                 |
    | `--sparse-values`  |            | Sparse vector values (inline JSON float32 array, `./path.json`, or `-` for stdin). Must be used together with `--sparse-indices`.                               |
    | `--top-k`          | `-k`       | Number of results to return (required)                                                                                                                          |
    | `--namespace`      |            | Namespace to search                                                                                                                                             |
    | `--filter`         |            | Metadata filter (inline JSON, `./path.json`, or `-` for stdin)                                                                                                  |
    | `--rerank`         |            | Re-score results using an inference model (inline JSON, `./path.json`, or `-` for stdin). Required fields: `model` (string), `rank_fields` (string array).      |
    | `--match-terms`    |            | Keyword terms filter for sparse integrated indexes (inline JSON, `./path.json`, or `-` for stdin). Required field: `terms` (string array). Requires `--inputs`. |
    | `--fields`         |            | Fields to return in results (inline JSON string array, `./path.json`, or `-` for stdin)                                                                         |
    | `--body`           |            | Full request body JSON (inline, `./path.json`, or `-` for stdin). Flags take precedence when both specify the same field.                                       |
    | `--json`           | `-j`       | Output in JSON format                                                                                                                                           |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Examples**

    ```bash theme={null}
    # Text search (integrated embedding indexes only)
    pc index record search --index-name my-index --inputs '{"text":"disease prevention"}' --top-k 10
    pc index record search --index-name my-index --inputs '{"text":"disease prevention"}' --namespace my-namespace --top-k 5
    pc index record search --index-name my-index --inputs '{"text":"disease prevention"}' --filter '{"category":"health"}' --top-k 10
    pc index record search --index-name my-index --inputs '{"text":"disease prevention"}' --fields '["_id","chunk_text","category"]' --top-k 10
    pc index record search --index-name my-index --inputs '{"text":"disease prevention"}' --rerank '{"model":"bge-reranker-v2-m3","rank_fields":["chunk_text"]}' --top-k 10
    pc index record search --index-name my-index --inputs '{"text":"disease prevention"}' --match-terms '{"terms":["vaccine","prevention"]}' --top-k 10

    # Search by record ID for query vector (all index types)
    pc index record search --index-name my-index --id rec-123 --top-k 10

    # Vector search (all index types)
    pc index record search --index-name my-index --vector '[0.1,0.2,0.3]' --top-k 10
    pc index record search --index-name my-index --sparse-indices '[1,5,9]' --sparse-values '[0.4,0.8,0.2]' --top-k 10
    pc index record search --index-name my-index --vector '[0.1,0.2,0.3]' --sparse-indices '[1,5,9]' --sparse-values '[0.4,0.8,0.2]' --top-k 10

    # Full request body (must include top_k in the body)
    pc index record search --index-name my-index --body ./search.json
    ```

    ```text CLI theme={null}
    Usage: 5 (read units)
    ID          SCORE       FIELDS
    rec-001     0.912340    {"category":"health","chunk_text":"vaccine research..."}
    rec-002     0.887210    {"category":"health","chunk_text":"disease prevention..."}
    ```
  </Accordion>

  <Accordion title="pc index record upsert (Upsert records into an integrated index)">
    **Description**

    Upsert records into an integrated index namespace from a JSON or JSONL payload.

    The `--body` flag accepts a JSON object containing a `"records"` array of `IntegratedRecord` objects, a raw JSON array of records, or a JSONL stream of records (one object per line). The value can be inline JSON, a path to a `.json` or `.jsonl` file, or `-` to read from stdin.

    Records are sent in batches. The default batch size is 96 (the API maximum). Use `--batch-size` to send smaller batches.

    **Usage**

    ```bash theme={null}
    pc index record upsert [flags]
    ```

    **Flags**

    | Long flag      | Short flag | Description                                                                             |
    | :------------- | :--------- | :-------------------------------------------------------------------------------------- |
    | `--index-name` | `-i`       | Name of the index to upsert into (required)                                             |
    | `--body`       |            | Request body JSON or JSONL (inline JSON, `./path.json[l]`, or `-` for stdin) (required) |
    | `--namespace`  |            | Namespace to upsert into                                                                |
    | `--batch-size` | `-b`       | Number of records per batch (default: `96`, max: `96`)                                  |
    | `--json`       | `-j`       | Output in JSON format                                                                   |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Examples**

    ```bash theme={null}
    # Upsert from a JSON file
    pc index record upsert --index-name my-index --body ./records.json

    # Upsert from a JSONL file into a specific namespace
    pc index record upsert --index-name my-index --namespace my-namespace --body ./records.jsonl

    # Upsert from stdin
    cat records.jsonl | pc index record upsert --index-name my-index --namespace my-namespace --body -
    ```
  </Accordion>
</AccordionGroup>

### Collections

<AccordionGroup>
  <Accordion title="pc index collection create (Create a collection from a pod-based index)">
    **Description**

    Creates a static copy of a pod-based index as a collection. Collections can be used to store a snapshot of an index's data for backup or migration purposes.

    **Usage**

    ```bash theme={null}
    pc index collection create [flags]
    ```

    **Flags**

    | Long flag  | Short flag | Description                                                 |
    | :--------- | :--------- | :---------------------------------------------------------- |
    | `--name`   | `-n`       | Name to give the collection (required)                      |
    | `--source` | `-s`       | Name of the pod-based index to use as the source (required) |
    | `--json`   | `-j`       | Output in JSON format                                       |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Create a collection from a pod-based index
    pc index collection create --name my-collection --source my-index
    ```

    ```text CLI theme={null}
    ATTRIBUTE     VALUE
    Name          my-collection
    State         Initializing
    Dimension     1536
    Size          0
    VectorCount   0
    Environment   us-east-1-aws
    ```
  </Accordion>

  <Accordion title="pc index collection delete (Delete a collection)">
    **Description**

    Deletes a collection permanently. This action cannot be undone.

    **Usage**

    ```bash theme={null}
    pc index collection delete [flags]
    ```

    **Flags**

    | Long flag             | Short flag | Description                                                |
    | :-------------------- | :--------- | :--------------------------------------------------------- |
    | `--name`              | `-n`       | Name of the collection to delete (required)                |
    | `--skip-confirmation` |            | Skip the deletion confirmation prompt                      |
    | `--json`              | `-j`       | Output in JSON format (also skips the confirmation prompt) |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Delete a collection (prompts for confirmation)
    pc index collection delete --name my-collection

    # Skip the confirmation prompt
    pc index collection delete --name my-collection --skip-confirmation
    ```

    <Note>
      This command prompts for confirmation before deleting. Pass `--skip-confirmation` (or `--json`) to bypass the prompt in non-interactive contexts.
    </Note>
  </Accordion>

  <Accordion title="pc index collection describe (Describe a collection by name)">
    **Description**

    Returns detailed information about a single collection, including its state, dimension, size, vector count, and environment.

    **Usage**

    ```bash theme={null}
    pc index collection describe [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description                                   |
    | :-------- | :--------- | :-------------------------------------------- |
    | `--name`  | `-n`       | Name of the collection to describe (required) |
    | `--json`  | `-j`       | Output in JSON format                         |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Describe a collection
    pc index collection describe --name my-collection
    ```

    ```text CLI theme={null}
    ATTRIBUTE     VALUE
    Name          my-collection
    State         Ready
    Dimension     1536
    Size          104857600
    VectorCount   10000
    Environment   us-east-1-aws
    ```
  </Accordion>

  <Accordion title="pc index collection list (List collections in your project)">
    **Description**

    Lists all collections in your current project, sorted alphabetically by name.

    **Usage**

    ```bash theme={null}
    pc index collection list [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description           |
    | :-------- | :--------- | :-------------------- |
    | `--json`  | `-j`       | Output in JSON format |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # List all collections
    pc index collection list
    ```

    ```text CLI theme={null}
    NAME             DIMENSION   SIZE        STATUS   VECTORS   ENVIRONMENT
    my-collection    1536        104857600   Ready    10000     us-east-1-aws
    ```
  </Accordion>
</AccordionGroup>

### Backups

<AccordionGroup>
  <Accordion title="pc index backup create (Create a backup)">
    **Description**

    Creates a backup of a serverless index. Backups are static copies that only consume storage.

    **Usage**

    ```bash theme={null}
    pc index backup create [flags]
    ```

    **Flags**

    | Long flag       | Short flag | Description                                                          |
    | :-------------- | :--------- | :------------------------------------------------------------------- |
    | `--index-name`  | `-i`       | Name of the index to back up (required)                              |
    | `--name`        |            | Human-readable label for the backup (the backup ID is always a UUID) |
    | `--description` | `-d`       | Description for the backup                                           |
    | `--json`        | `-j`       | Output in JSON format                                                |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Create a backup
    pc index backup create -i my-index

    # Create with name and description
    pc index backup create -i my-index --name "nightly-backup" -d "Nightly backup before deployment"

    # JSON output
    pc index backup create -i my-index -j
    ```
  </Accordion>

  <Accordion title="pc index backup delete (Delete a backup)">
    **Description**

    Permanently deletes a backup. This operation cannot be undone.

    **Usage**

    ```bash theme={null}
    pc index backup delete [flags]
    ```

    **Flags**

    | Long flag             | Short flag | Description                                                |
    | :-------------------- | :--------- | :--------------------------------------------------------- |
    | `--id`                | `-i`       | Backup ID to delete (required)                             |
    | `--skip-confirmation` |            | Skip the deletion confirmation prompt                      |
    | `--json`              | `-j`       | Output in JSON format (also skips the confirmation prompt) |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Delete a backup by ID (prompts for confirmation)
    pc index backup delete -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f

    # Skip the confirmation prompt
    pc index backup delete -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f --skip-confirmation
    ```

    <Note>
      This command prompts for confirmation before deleting. Pass `--skip-confirmation` (or `--json`) to bypass the prompt in non-interactive contexts.
    </Note>

    <Warning>
      Backup deletion is permanent and cannot be undone.
    </Warning>
  </Accordion>

  <Accordion title="pc index backup describe (Show backup details)">
    **Description**

    Displays detailed information about a specific backup.

    **Usage**

    ```bash theme={null}
    pc index backup describe [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description                      |
    | :-------- | :--------- | :------------------------------- |
    | `--id`    | `-i`       | Backup ID to describe (required) |
    | `--json`  | `-j`       | Output in JSON format            |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Describe a backup
    pc index backup describe -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f

    # JSON output
    pc index backup describe -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f -j
    ```
  </Accordion>

  <Accordion title="pc index backup list (List backups)">
    **Description**

    Lists backups in the current project, optionally filtered by index name.

    **Usage**

    ```bash theme={null}
    pc index backup list [flags]
    ```

    **Flags**

    | Long flag            | Short flag | Description                    |
    | :------------------- | :--------- | :----------------------------- |
    | `--index-name`       | `-i`       | Filter backups by index name   |
    | `--limit`            | `-l`       | Maximum number of results      |
    | `--pagination-token` | `-p`       | Pagination token for next page |
    | `--json`             | `-j`       | Output in JSON format          |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # List all backups in the project
    pc index backup list

    # List backups for a specific index
    pc index backup list --index-name my-index

    # Limit results
    pc index backup list --limit 10

    # JSON output
    pc index backup list -j
    ```
  </Accordion>

  <Accordion title="pc index restore (Restore an index from a backup)">
    **Description**

    Creates a new index from a backup.

    **Usage**

    ```bash theme={null}
    pc index restore [flags]
    ```

    **Flags**

    | Long flag               | Short flag | Description                                          |
    | :---------------------- | :--------- | :--------------------------------------------------- |
    | `--id`                  | `-i`       | Backup ID (UUID) to restore from (required)          |
    | `--name`                | `-n`       | Name for the new index (required)                    |
    | `--deletion-protection` |            | Enable deletion protection - `enabled` or `disabled` |
    | `--tags`                | `-t`       | Tags to apply to the new index (key=value pairs)     |
    | `--json`                | `-j`       | Output in JSON format                                |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Restore an index from a backup
    pc index restore -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f -n restored-index

    # Restore with tags and deletion protection
    pc index restore -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f -n restored-index \
      --tags env=prod,team=search \
      --deletion-protection enabled

    # JSON output
    pc index restore -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f -n restored-index -j
    ```
  </Accordion>

  <Accordion title="pc index restore describe (Show restore job details)">
    **Description**

    Displays the status and details of a restore job.

    **Usage**

    ```bash theme={null}
    pc index restore describe [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description                           |
    | :-------- | :--------- | :------------------------------------ |
    | `--id`    | `-i`       | Restore job ID to describe (required) |
    | `--json`  | `-j`       | Output in JSON format                 |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Describe a restore job
    pc index restore describe -i rj-abc123

    # JSON output
    pc index restore describe -i rj-abc123 -j
    ```
  </Accordion>

  <Accordion title="pc index restore list (List restore jobs)">
    **Description**

    Lists all restore jobs in the current project.

    **Usage**

    ```bash theme={null}
    pc index restore list [flags]
    ```

    **Flags**

    | Long flag            | Short flag | Description                    |
    | :------------------- | :--------- | :----------------------------- |
    | `--limit`            | `-l`       | Maximum number of results      |
    | `--pagination-token` | `-p`       | Pagination token for next page |
    | `--json`             | `-j`       | Output in JSON format          |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # List restore jobs
    pc index restore list

    # Limit results
    pc index restore list --limit 10

    # JSON output
    pc index restore list -j
    ```
  </Accordion>
</AccordionGroup>

### Imports

<AccordionGroup>
  <Accordion title="pc index import start (Start an import from a storage URI)">
    **Description**

    Start an import that loads vector data from a storage provider into a serverless index. The URI must begin with the scheme of a supported provider (for example, `s3://`).

    For private buckets, configure a storage integration in the Pinecone console and pass the integration ID with `--integration-id`.

    Use `--error-mode` to control behavior when records fail: `continue` skips failing records and keeps going; `abort` stops the import on first error. Defaults to `continue`.

    **Usage**

    ```bash theme={null}
    pc index import start [flags]
    ```

    **Flags**

    | Long flag          | Short flag | Description                                                           |
    | :----------------- | :--------- | :-------------------------------------------------------------------- |
    | `--index-name`     | `-i`       | Name of the index to import into (required)                           |
    | `--uri`            | `-u`       | URI of the data to import, for example `s3://bucket/path/` (required) |
    | `--integration-id` |            | Storage integration ID for private buckets                            |
    | `--error-mode`     |            | How to handle record errors: `continue` (default) or `abort`          |
    | `--json`           | `-j`       | Output in JSON format                                                 |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Examples**

    ```bash theme={null}
    # Start an import from a public S3 bucket
    pc index import start --index-name my-index --uri s3://my-bucket/data/

    # Start an import from a private bucket using a storage integration
    pc index import start --index-name my-index --uri s3://my-bucket/data/ --integration-id intg-123

    # Abort on the first error instead of continuing
    pc index import start --index-name my-index --uri s3://my-bucket/data/ --error-mode abort

    # JSON output
    pc index import start --index-name my-index --uri s3://my-bucket/data/ -j
    ```

    ```text CLI theme={null}
    Import imp-abc123 started.
    ATTRIBUTE    VALUE
    Import ID    imp-abc123
    ```
  </Accordion>

  <Accordion title="pc index import describe (Describe an import operation)">
    **Description**

    Show the current status and details of an import operation, including
    percent complete, records imported, and any error messages.

    **Usage**

    ```bash theme={null}
    pc index import describe [flags]
    ```

    **Flags**

    | Long flag      | Short flag | Description                                        |
    | :------------- | :--------- | :------------------------------------------------- |
    | `--index-name` | `-i`       | Name of the index the import belongs to (required) |
    | `--id`         |            | ID of the import to describe (required)            |
    | `--json`       | `-j`       | Output in JSON format                              |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Describe an import operation
    pc index import describe --index-name my-index --id import-123

    # JSON output
    pc index import describe --index-name my-index --id import-123 -j
    ```

    ```text CLI theme={null}
    ATTRIBUTE         VALUE
    Import ID         import-123
    Status            InProgress
    URI               s3://my-bucket/data/
    Percent Complete  45.0%
    Records Imported  450
    Created At        2024-01-15 12:00:00
    Finished At       -
    Error             None
    ```
  </Accordion>

  <Accordion title="pc index import list (List import operations for an index)">
    **Description**

    List bulk import operations for the given index, with optional pagination.

    **Usage**

    ```bash theme={null}
    pc index import list [flags]
    ```

    **Flags**

    | Long flag            | Short flag | Description                                               |
    | :------------------- | :--------- | :-------------------------------------------------------- |
    | `--index-name`       | `-i`       | Name of the index to list imports for (required)          |
    | `--limit`            | `-l`       | Maximum number of imports to return                       |
    | `--pagination-token` | `-p`       | Pagination token to continue a previous listing operation |
    | `--json`             | `-j`       | Output in JSON format                                     |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Examples**

    ```bash theme={null}
    # List all imports for an index
    pc index import list --index-name my-index

    # List imports with a page size limit
    pc index import list --index-name my-index --limit 10

    # Continue paginating from a previous call
    pc index import list --index-name my-index --pagination-token eyJ...

    # JSON output
    pc index import list --index-name my-index -j
    ```

    ```text CLI theme={null}
    IMPORT ID     STATUS      URI                     PERCENT  RECORDS  CREATED              FINISHED
    imp-abc123    Completed   s3://my-bucket/data/    100.0%   1000     2024-01-15 12:00:00  2024-01-15 12:05:00
    imp-def456    InProgress  s3://other-bucket/data/ 45.0%    450      2024-01-15 13:00:00  -
    ```
  </Accordion>

  <Accordion title="pc index import cancel (Cancel an in-progress import operation)">
    **Description**

    Cancel an import operation that is currently pending or in progress.
    Already-completed or failed imports cannot be canceled.

    **Usage**

    ```bash theme={null}
    pc index import cancel [flags]
    ```

    **Flags**

    | Long flag      | Short flag | Description                                        |
    | :------------- | :--------- | :------------------------------------------------- |
    | `--index-name` | `-i`       | Name of the index the import belongs to (required) |
    | `--id`         |            | ID of the import to cancel (required)              |
    | `--json`       | `-j`       | Output in JSON format                              |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Cancel an import operation
    pc index import cancel --index-name my-index --id import-123

    # JSON output
    pc index import cancel --index-name my-index --id import-123 -j
    ```

    ```text CLI theme={null}
    Import import-123 canceled.
    ```
  </Accordion>
</AccordionGroup>

### Projects

<AccordionGroup>
  <Accordion title="pc project create (Create a new project)">
    **Description**

    Creates a new project in your [target organization](/reference/cli/target-context), using the specified configuration.

    **Usage**

    ```bash theme={null}
    pc project create [flags]
    ```

    **Flags**

    | Long flag            | Short flag | Description                                                    |
    | :------------------- | :--------- | :------------------------------------------------------------- |
    | `--force-encryption` |            | Enable encryption with CMEK                                    |
    | `--json`             | `-j`       | Output in JSON format                                          |
    | `--name`             | `-n`       | Project name (required)                                        |
    | `--target`           |            | Automatically target the project in the CLI after it's created |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Basic project creation
    pc project create -n "demo-project"
    ```
  </Accordion>

  <Accordion title="pc project delete (Delete a project)">
    **Description**

    Permanently deletes a project and all its resources. This operation cannot be undone.

    **Usage**

    ```bash theme={null}
    pc project delete [flags]
    ```

    **Flags**

    | Long flag             | Short flag | Description                                                 |
    | :-------------------- | :--------- | :---------------------------------------------------------- |
    | `--id`                | `-i`       | Project ID (optional, uses target project if not specified) |
    | `--json`              | `-j`       | Output in JSON format                                       |
    | `--skip-confirmation` |            | Skip confirmation prompt                                    |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Delete target project
    pc project delete

    # Delete specific project
    pc project delete -i proj-abc123

    # Skip confirmation
    pc project delete -i proj-abc123 --skip-confirmation
    ```

    <Note>
      Must delete all indexes and collections in the project first. If the deleted project is your current target, set a new target after deleting it.
    </Note>
  </Accordion>

  <Accordion title="pc project describe (Show project details)">
    **Description**

    Displays detailed information about a specific project, including various details.

    **Usage**

    ```bash theme={null}
    pc project describe [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description           |
    | :-------- | :--------- | :-------------------- |
    | `--id`    | `-i`       | Project ID (required) |
    | `--json`  | `-j`       | Output in JSON format |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Describe a project
    pc project describe -i proj-abc123

    # JSON output
    pc project describe -i proj-abc123 --json

    # Find ID and describe
    pc project list
    pc project describe -i proj-abc123
    ```
  </Accordion>

  <Accordion title="pc project list (List all projects)">
    **Description**

    Displays all projects in your [target organization](/reference/cli/target-context), including various details.

    **Usage**

    ```bash theme={null}
    pc project list [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description           |
    | :-------- | :--------- | :-------------------- |
    | `--json`  | `-j`       | Output in JSON format |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # List all projects
    pc project list

    # JSON output
    pc project list --json

    # List after login
    pc auth login
    pc auth target -o "my-org"
    pc project list
    ```
  </Accordion>

  <Accordion title="pc project update (Update project settings)">
    **Description**

    Modifies the configuration of the [target project](/reference/cli/target-context), or a specific project ID.

    **Usage**

    ```bash theme={null}
    pc project update [flags]
    ```

    **Flags**

    | Long flag            | Short flag | Description                         |
    | :------------------- | :--------- | :---------------------------------- |
    | `--force-encryption` | `-f`       | Enable/disable encryption with CMEK |
    | `--id`               | `-i`       | Project ID (required)               |
    | `--json`             | `-j`       | Output in JSON format               |
    | `--name`             | `-n`       | New project name                    |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Update name
    pc project update -i proj-abc123 -n "new-name"
    ```
  </Accordion>
</AccordionGroup>

### Organizations

<AccordionGroup>
  <Accordion title="pc organization delete (Delete an organization)">
    **Description**

    Permanently deletes an organization and all its resources. This operation cannot be undone.

    **Usage**

    ```bash theme={null}
    pc organization delete [flags]
    ```

    **Flags**

    | Long flag             | Short flag | Description                |
    | :-------------------- | :--------- | :------------------------- |
    | `--id`                | `-i`       | Organization ID (required) |
    | `--json`              | `-j`       | Output in JSON format      |
    | `--skip-confirmation` |            | Skip confirmation prompt   |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Delete an organization
    pc organization delete -i org-abc123

    # Skip confirmation
    pc organization delete -i org-abc123 --skip-confirmation
    ```

    <Note>
      This is a highly destructive action. Deletion is permanent. If the deleted organization is your current [target](/reference/cli/target-context), set a new target after deleting.
    </Note>
  </Accordion>

  <Accordion title="pc organization describe (Show organization details)">
    **Description**

    Displays detailed information about a specific organization, including name, ID, creation date, payment status, plan, and support tier.

    **Usage**

    ```bash theme={null}
    pc organization describe [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description                |
    | :-------- | :--------- | :------------------------- |
    | `--id`    | `-i`       | Organization ID (required) |
    | `--json`  | `-j`       | Output in JSON format      |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Describe an organization
    pc organization describe -i org-abc123

    # JSON output
    pc organization describe -i org-abc123 --json

    # Find ID and describe
    pc organization list
    pc organization describe -i org-abc123
    ```
  </Accordion>

  <Accordion title="pc organization list (List organizations)">
    **Description**

    Displays all organizations that the authenticated user has access to, including name, ID, creation date, payment status, plan, and support tier.

    **Usage**

    ```bash theme={null}
    pc organization list [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description           |
    | :-------- | :--------- | :-------------------- |
    | `--json`  | `-j`       | Output in JSON format |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # List all organizations
    pc organization list

    # JSON output
    pc organization list --json

    # List after login
    pc auth login
    pc organization list
    ```
  </Accordion>

  <Accordion title="pc organization update (Update organization settings)">
    **Description**

    Modifies the configuration of the [target organization](/reference/cli/target-context), or a specific organization ID.

    **Usage**

    ```bash theme={null}
    pc organization update [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description                |
    | :-------- | :--------- | :------------------------- |
    | `--id`    | `-i`       | Organization ID (required) |
    | `--json`  | `-j`       | Output in JSON format      |
    | `--name`  | `-n`       | New organization name      |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Update name
    pc organization update -i org-abc123 -n "new-name"

    # Verify changes
    pc organization update -i org-abc123 -n "Acme Corp"
    pc organization describe -i org-abc123
    ```
  </Accordion>
</AccordionGroup>

### API keys

<AccordionGroup>
  <Accordion title="pc api-key create (Create a new API key)">
    **Description**

    Creates a new API key for the current [target project](/reference/cli/target-context) or a specific project ID. Optionally stores the key locally for CLI use.

    **Usage**

    ```bash theme={null}
    pc api-key create [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description                                                                             |
    | :-------- | :--------- | :-------------------------------------------------------------------------------------- |
    | `--id`    | `-i`       | Project ID (optional, uses target project if not specified)                             |
    | `--json`  | `-j`       | Output in JSON format                                                                   |
    | `--name`  | `-n`       | Key name (required)                                                                     |
    | `--roles` |            | Roles to assign (default: `ProjectEditor`)                                              |
    | `--store` |            | Store the key locally for CLI use (automatically replaces any existing CLI-managed key) |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Basic key creation
    pc api-key create -n "my-key"

    # Create and store locally
    pc api-key create -n "my-key" --store

    # Create with specific role
    pc api-key create -n "my-key" --store --roles ProjectEditor

    # Create for specific project
    pc api-key create -n "my-key" -i proj-abc123
    ```

    <Note>
      API keys are scoped to a specific organization and project.
    </Note>
  </Accordion>

  <Accordion title="pc api-key delete (Delete an API key)">
    **Description**

    Permanently deletes an API key. Applications using this key immediately lose access.

    **Usage**

    ```bash theme={null}
    pc api-key delete [flags]
    ```

    **Flags**

    | Long flag             | Short flag | Description              |
    | :-------------------- | :--------- | :----------------------- |
    | `--id`                | `-i`       | API key ID (required)    |
    | `--skip-confirmation` |            | Skip confirmation prompt |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Delete an API key
    pc api-key delete -i key-abc123

    # Skip confirmation
    pc api-key delete -i key-abc123 --skip-confirmation

    # Delete and clean up local storage
    pc api-key delete -i key-abc123
    pc auth local-keys prune --skip-confirmation
    ```

    <Note>
      Deletion is permanent. Applications using this key immediately lose access to Pinecone.
    </Note>
  </Accordion>

  <Accordion title="pc api-key describe (Show API key details)">
    **Description**

    Displays detailed information about a specific API key, including its name, ID, project ID, and roles.

    **Usage**

    ```bash theme={null}
    pc api-key describe [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description           |
    | :-------- | :--------- | :-------------------- |
    | `--id`    | `-i`       | API key ID (required) |
    | `--json`  | `-j`       | Output in JSON format |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Describe an API key
    pc api-key describe -i key-abc123

    # JSON output
    pc api-key describe -i key-abc123 --json

    # Find ID and describe
    pc api-key list
    pc api-key describe -i key-abc123
    ```

    <Note>
      Does not display the actual key value.
    </Note>
  </Accordion>

  <Accordion title="pc api-key list (List all API keys)">
    **Description**

    Displays a list of all of the [target project's](/reference/cli/target-context) API keys, as found in  Pinecone (regardless of whether they are stored locally by the CLI). Displays various details about each key, including name, ID, project ID, and roles.

    **Usage**

    ```bash theme={null}
    pc api-key list [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description                                                 |
    | :-------- | :--------- | :---------------------------------------------------------- |
    | `--id`    | `-i`       | Project ID (optional, uses target project if not specified) |
    | `--json`  | `-j`       | Output in JSON format                                       |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # List keys for target project
    pc api-key list

    # List for specific project
    pc api-key list -i proj-abc123

    # JSON output
    pc api-key list --json
    ```

    <Note>
      Does not display key values.
    </Note>
  </Accordion>

  <Accordion title="pc api-key update (Update API key settings)">
    **Description**

    Updates the name and roles of an API key.

    **Usage**

    ```bash theme={null}
    pc api-key update [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description           |
    | :-------- | :--------- | :-------------------- |
    | `--id`    | `-i`       | API key ID (required) |
    | `--json`  | `-j`       | Output in JSON format |
    | `--name`  | `-n`       | New key name          |
    | `--roles` | `-r`       | Roles to assign       |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Update name
    pc api-key update -i key-abc123 -n "new-name"

    # Update roles
    pc api-key update -i key-abc123 -r ProjectEditor

    # Verify changes
    pc api-key update -i key-abc123 -n "production-key"
    pc api-key describe -i key-abc123
    ```

    <Note>
      Cannot change the actual key. If you need a different key, create a new one.
    </Note>
  </Accordion>
</AccordionGroup>

### Config

<AccordionGroup>
  <Accordion title="pc config list (List all configuration settings and their current values)">
    **Description**

    Lists all CLI configuration settings and their current values. Sensitive values like `api-key` are masked by default; use `--reveal` to see the full value. Hidden settings such as `environment` are included when `--all` is passed.

    **Usage**

    ```bash theme={null}
    pc config list [flags]
    ```

    **Flags**

    | Long flag  | Short flag | Description                                               |
    | :--------- | :--------- | :-------------------------------------------------------- |
    | `--reveal` |            | Reveal the full value for sensitive settings like api-key |
    | `--json`   | `-j`       | Output in JSON format                                     |
    | `--all`    |            | Include hidden settings such as environment               |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    pc config list
    pc config list --all
    pc config list --reveal
    pc config list --json
    ```

    ```text CLI theme={null}
    KEY         VALUE             ENV VAR NAME        ENV VAR OVERRIDE  DESCRIPTION
    api-key     ****abcd****      PINECONE_API_KEY     false             Default API key for authenticating with Pinecone
    color       true                                                     Enable colored output
    ```
  </Accordion>

  <Accordion title="pc config get <key> (Get the current value of a configuration setting)">
    **Description**

    Gets the current value of a configuration setting. Valid keys are: `api-key`, `color`, `environment`. Sensitive values like `api-key` are masked by default; use `--reveal` to see the full value.

    **Usage**

    ```bash theme={null}
    pc config get <key> [flags]
    ```

    **Flags**

    | Long flag  | Short flag | Description                                               |
    | :--------- | :--------- | :-------------------------------------------------------- |
    | `--reveal` |            | Reveal the full value for sensitive settings like api-key |
    | `--json`   | `-j`       | Output in JSON format                                     |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    pc config get api-key
    pc config get api-key --reveal
    pc config get environment
    pc config get color
    ```
  </Accordion>

  <Accordion title="pc config describe <key> (Show detailed information about a configuration setting)">
    **Description**

    Displays detailed information about a specific CLI configuration setting, including its current value, whether an environment variable is overriding it, and valid values. Valid keys are: `api-key`, `color`, `environment`.

    **Usage**

    ```bash theme={null}
    pc config describe <key> [flags]
    ```

    **Flags**

    | Long flag  | Short flag | Description                                               |
    | :--------- | :--------- | :-------------------------------------------------------- |
    | `--reveal` |            | Reveal the full value for sensitive settings like api-key |
    | `--json`   | `-j`       | Output in JSON format                                     |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    pc config describe api-key
    pc config describe color
    pc config describe color --json
    ```

    ```text CLI theme={null}
    KEY               api-key
    VALUE             ****abcd****
    ENV VAR NAME      $PINECONE_API_KEY
    ENV VAR OVERRIDE  false
    SENSITIVE         true
    DESCRIPTION       Default API key for authenticating with Pinecone
    ```
  </Accordion>

  <Accordion title="pc config set <key> <value> (Set a configuration value)">
    **Description**

    Sets a CLI configuration value. Valid keys are: `api-key`, `color`, `environment`. The value is persisted to the local config file.

    **Usage**

    ```bash theme={null}
    pc config set <key> <value> [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description           |
    | :-------- | :--------- | :-------------------- |
    | `--json`  | `-j`       | Output in JSON format |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    pc config set api-key pcsk_...
    pc config set environment staging
    pc config set color false
    ```
  </Accordion>

  <Accordion title="pc config unset <key> (Reset a configuration value to its default)">
    **Description**

    Resets a CLI configuration value to its default. Valid keys are: `api-key`, `color`, `environment`.

    **Usage**

    ```bash theme={null}
    pc config unset <key> [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description           |
    | :-------- | :--------- | :-------------------- |
    | `--json`  | `-j`       | Output in JSON format |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    pc config unset api-key
    pc config unset color
    ```
  </Accordion>
</AccordionGroup>


# CLI quickstart
Source: https://docs.pinecone.io/reference/cli/quickstart

Pinecone CLI quickstart for installing pc, authenticating, and managing indexes, vectors, and data imports directly from your terminal.

The Pinecone CLI (`pc`) lets you manage Pinecone resources directly from your terminal.

## Install

<Tabs>
  <Tab title="macOS (Homebrew)">
    ```bash theme={null}
    brew tap pinecone-io/tap
    brew install pinecone-io/tap/pinecone
    ```
  </Tab>

  <Tab title="Other platforms">
    Pre-built binaries for macOS, Linux, and Windows are available on the [GitHub Releases page](https://github.com/pinecone-io/cli/releases).

    | Platform | Architectures                          |
    | :------- | :------------------------------------- |
    | macOS    | Intel (x86\_64), Apple Silicon (ARM64) |
    | Linux    | x86\_64, ARM64, i386                   |
    | Windows  | x86\_64, i386                          |
  </Tab>
</Tabs>

## Authenticate

```bash theme={null}
pc auth login
```

Visit the URL in your terminal to sign in. The CLI automatically sets your default organization and project.

To target a different org/project:

```bash theme={null}
pc target -o "my-org" -p "my-project"
```

<Tip>
  For CI/CD or automation, you can also authenticate with a [service account](/reference/cli/authentication#service-account) or [API key](/reference/cli/authentication#api-key).
</Tip>

## Manage indexes

```bash theme={null}
# List indexes
pc index list

# Create an index
pc index create -n my-index -d 3 -m cosine -c aws -r us-east-1

# Get index details
pc index describe -i my-index

# Get index statistics
pc index stats -i my-index
```

## Work with vectors

```bash theme={null}
# Upsert vectors (from file or inline JSON)
pc index vector upsert -i my-index \
  --body '{"vectors": [{"id": "vec1", "values": [0.1, 0.2, 0.3], "metadata": {"genre": "comedy"}}]}'

# Import from a large dataset in object storage (S3, GCS, Azure)
pc index import start -i my-index --uri s3://my-bucket/data/

# Check the progress of an import operation
pc index import list --i my-index
pc index import describe --i my-index --id import-123

# Query (vector can be inline or in a file)
pc index vector query -i my-index \
  --vector '[0.1, 0.2, 0.3]' \
  --top-k 10 \
  --include-metadata

# Fetch by ID (from file or inline JSON)
pc index vector fetch -i my-index --ids '["vec1","vec2"]'

# List vector IDs from an index
pc index vector list -i my-index
```

## Manage namespaces

```bash theme={null}
# List namespaces
pc index namespace list -i my-index

# Create a namespace
pc index namespace create -i my-index --name tenant-a

# Delete a namespace
pc index namespace delete -i my-index --name tenant-a
```

## Back up and restore

```bash theme={null}
# Create a backup
pc index backup create -i my-index --name "my-index-backup"

# List backups (show index, backup name, backup ID, etc.)
pc index backup list -i my-index

# Restore from backup (by ID, not name)
pc index restore -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f -n restored-index
```

## JSON output

Add `-j` to any command for JSON output:

```bash theme={null}
pc index list -j
pc index describe -i my-index -j
```

## Getting help

Use `-h` or `--help` with any command to see available options:

```bash theme={null}
pc -h
pc index -h
pc index create -h
```

## Next steps

* [Command reference](/reference/cli/command-reference) — Full list of commands and flags
* [Authentication](/reference/cli/authentication) — Service accounts, API keys, and auth priority
* [Target context](/reference/cli/target-context) — How org/project targeting works


# CLI target context
Source: https://docs.pinecone.io/reference/cli/target-context

Pinecone CLI: The CLI's **target context** determines which organization and project your commands operate on. You must authenticate before setting target.

The CLI's **target context** determines which organization and project your commands operate on. You must [authenticate](/reference/cli/authentication) before setting target context.

## Flags

| Flag                | Short | Default | Description                                                                       |
| ------------------- | ----- | ------- | --------------------------------------------------------------------------------- |
| `--org`             | `-o`  | —       | Target organization by name. Mutually exclusive with `--organization-id`.         |
| `--organization-id` | —     | —       | Target organization by ID. Mutually exclusive with `--org`.                       |
| `--project`         | `-p`  | —       | Target project by name. Mutually exclusive with `--project-id`.                   |
| `--project-id`      | —     | —       | Target project by ID. Mutually exclusive with `--project`.                        |
| `--show`            | `-s`  | `false` | Show the current target context.                                                  |
| `--clear`           | —     | `false` | Clear the stored target context.                                                  |
| `--json`            | `-j`  | `false` | Output as JSON. In non-TTY environments (CI/CD, pipes), JSON output is automatic. |

<Note>
  `--org` and `--organization-id` are mutually exclusive — use one or the other. The same applies to `--project` and `--project-id`.
</Note>

## How operations use target context

| Operation type                   | Scope                                    |
| -------------------------------- | ---------------------------------------- |
| Control plane (indexes, backups) | Target project                           |
| Data plane (vectors, namespaces) | Target project + specified index         |
| Admin API (organizations)        | No target context needed                 |
| Admin API (projects)             | Target organization                      |
| Admin API (API keys)             | Target project (unless `--id` specified) |

## Target context by auth method

### User login

After `pc auth login`, the CLI auto-targets your default organization and its first project.

```bash theme={null}
# Change target
pc target -o "my-org" -p "my-project"
```

### Service account

**Via CLI command:** After `pc auth configure --client-id --client-secret`, the CLI auto-targets the service account's organization. For the project:

* If one project exists, it's auto-targeted
* If multiple exist, you're prompted (or use `--project-id`)
* If none exist, create one and target it manually

**Via environment variables:** If using `PINECONE_CLIENT_ID` and `PINECONE_CLIENT_SECRET` without running `pc auth configure`, no target context is set automatically. Run `pc target` to set it.

```bash theme={null}
# Change project (org is fixed to the service account's org)
pc target -p "my-project"

# Or select interactively
pc target
```

### API key

<Warning>
  When using an API key, control plane and data plane operations use the **key's org/project scope**, not the CLI's stored target context. The `pc target --show` output does not reflect what these operations actually use.
</Warning>

API keys are scoped to a specific org and project and cannot access resources outside that scope.

Admin API operations still use your user login or service account credentials (API keys can't authenticate Admin API calls).

## Managing target context

```bash theme={null}
pc target --show   # View current target
pc target --clear  # Clear target context
```

### JSON mode and non-TTY environments

Running `pc target --json` with no targeting flags returns the current target context as a JSON object. This is a local-state read — **no authentication is required**:

```bash theme={null}
pc target --json
```

In non-TTY environments (CI/CD pipelines, shell pipes, scripts), JSON output is automatic — the same as passing `--json` explicitly. You do not need to add the flag in automation contexts.

Use `--organization-id` and `--project-id` (instead of name flags) to set context reliably in scripts, since IDs are stable and unaffected by renames:

```bash theme={null}
pc target --organization-id "org-abc123" --project-id "proj-xyz789" --json
```


# Pinecone SDKs overview
Source: https://docs.pinecone.io/reference/pinecone-sdks

Browse official Pinecone SDKs for Python, Node.js, Java, and Go, including the version mappings between SDK releases and API versions.

## Pinecone SDKs

Official Pinecone SDKs provide convenient access to the [Pinecone APIs](/reference/api/introduction).

<CardGroup>
  <Card title="Python SDK" icon="python" href="/reference/sdks/python/overview" />

  <Card title="Node.js SDK" icon="node-js" href="/reference/sdks/node/overview" />

  <Card title="Java SDK" icon="java" href="/reference/sdks/java/overview" />

  <Card title="Go SDK" icon="golang" href="/reference/sdks/go/overview" />
</CardGroup>

## SDK versions

SDK versions are pinned to specific [API versions](/reference/api/versioning). When a new API version is released, a new version of the SDK is also released.

The mappings between API versions and SDK versions are as follows:

|                                               | `2026-04`   | `2025-10` | `2025-04` | `2025-01` | `2024-10` | `2024-07`     | `2024-04` |
| --------------------------------------------- | :---------- | :-------- | :-------- | :-------- | :-------- | :------------ | :-------- |
| [Python SDK](/reference/sdks/python/overview) | v9.x        | v8.x      | v7.x      | v6.x      | v5.3.x    | v5.0.x-v5.2.x | v4.x      |
| [Node.js SDK](/reference/sdks/node/overview)  | v8.x        | v7.x      | v6.x      | v5.x      | v4.x      | v3.x          | v2.x      |
| [Java SDK](/reference/sdks/java/overview)     | Coming soon | v6.x      | v5.x      | v4.x      | v3.x      | v2.x          | v1.x      |
| [Go SDK](/reference/sdks/go/overview)         | v6.x        | v5.x      | v4.x      | v3.x      | v2.x      | v1.x          | v0.x      |

When a new stable API version is released, you should upgrade your SDK to the latest version to ensure compatibility with the latest API changes.

<Note>
  The Java SDK targeting API version `2026-04` will be available soon.
</Note>

## Limitations

While Pinecone tracks read unit usage with decimal precision, the Pinecone API and SDKs round these values up to the nearest whole number in query, fetch, and list responses. For example, if a query uses 0.45 read units, the API and SDKs will report it as 1 read unit.

For precise read unit reporting, see [index-level metrics](/guides/production/monitoring) or the organization-wide [Usage dashboard](/guides/manage-cost/monitor-usage-and-costs#monitor-organization-level-usage-and-costs).

## Community SDKs

Find community-contributed SDKs for Pinecone. These libraries are not supported by Pinecone.

* [Ruby SDK](https://github.com/ScotterC/pinecone) (contributed by [ScotterC](https://github.com/ScotterC))

* [Scala SDK](https://github.com/cequence-io/pinecone-scala) (contributed by [cequence-io](https://github.com/cequence-io))

* [PHP SDK](https://github.com/probots-io/pinecone-php) (contributed by [protobots-io](https://github.com/probots-io))


# Pinecone Go SDK
Source: https://docs.pinecone.io/reference/sdks/go/overview

Install and use the Pinecone Go SDK to manage indexes and namespaces, upsert vectors, run semantic search, and call the Admin and Inference APIs from Go.

<Tip>
  For installation instructions and usage examples, see the [Go SDK documentation](https://github.com/pinecone-io/go-pinecone). To report an issue or request a feature, [file an issue on GitHub](https://github.com/pinecone-io/go-pinecone/issues).
</Tip>

## Requirements

The Pinecone Go SDK requires a Go version with [modules](https://go.dev/wiki/Modules) support.

## SDK versions

SDK versions are pinned to specific [API versions](/reference/api/versioning). When a new API version is released, a new version of the SDK is also released.

The mappings between API versions and Go SDK versions are as follows:

| API version | SDK version |
| :---------- | :---------- |
| `2026-04`   | v6.x        |
| `2025-10`   | v5.x        |
| `2025-04`   | v4.x        |
| `2025-01`   | v3.x        |
| `2024-10`   | v2.x        |
| `2024-07`   | v1.x        |
| `2024-04`   | v0.x        |

When a new stable API version is released, you should upgrade your SDK to the latest version to ensure compatibility with the latest API changes.

## Install

To install the latest version of the [Go SDK](https://github.com/pinecone-io/go-pinecone), add a dependency to the current module:

```shell theme={null}
go get github.com/pinecone-io/go-pinecone/v6/pinecone
```

To install a specific version of the Go SDK, run the following command:

```shell theme={null}
go get github.com/pinecone-io/go-pinecone/v6/pinecone@<version>
```

To check your SDK version, run the following command:

```shell theme={null}
go list -u -m all | grep go-pinecone
```

## Upgrade

<Warning>
  Before upgrading to `v3.0.0` or later, update all relevant code to account for the breaking changes explained [here](/release-notes/2025#2025-02-07-4).
</Warning>

Each major version carries its version number in the module path, so crossing a major requires updating the import path in every file that uses the SDK. For example, moving from `v4` to `v6` means changing:

```go theme={null}
// before
import "github.com/pinecone-io/go-pinecone/v4/pinecone"

// after
import "github.com/pinecone-io/go-pinecone/v6/pinecone"
```

Apart from the module path, `v5.0.0` and `v6.0.0` are backward compatible with the release lines before them.

If you already have the Go SDK, upgrade to the latest version as follows:

```shell theme={null}
go get -u github.com/pinecone-io/go-pinecone/v6/pinecone@latest
```

## Initialize

Once installed, you can import the SDK and then use an [API key](/guides/production/security-overview#api-keys) to initialize a client instance:

```Go theme={null}
package main

import (
    "context"
    "log"

    "github.com/pinecone-io/go-pinecone/v6/pinecone"
)

func main() {
    ctx := context.Background()

    pc, err := pinecone.NewClient(pinecone.NewClientParams{
        ApiKey: "YOUR_API_KEY",
    })
    if err != nil {
        log.Fatalf("Failed to create Client: %v", err)
    }
} 
```

To manage organizations, projects, API keys, and [role-based access control](/guides/production/manage-rbac), initialize an `AdminClient` with [service account](/guides/organizations/manage-service-accounts) credentials instead:

```Go theme={null}
package main

import (
    "context"
    "log"
    "os"

    "github.com/pinecone-io/go-pinecone/v6/pinecone"
)

func main() {
    ctx := context.Background()

    adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
        ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
        ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
    })
    if err != nil {
        log.Fatalf("Failed to create AdminClient: %v", err)
    }
}
```


# Reference
Source: https://docs.pinecone.io/reference/sdks/go/reference

Reference documentation for the Pinecone Go SDK, including client setup, types, and methods for managing indexes and vector data operations.



# OpenTelemetry support
Source: https://docs.pinecone.io/reference/sdks/java/open-telemetry

Monitor Pinecone Java SDK operations with OpenTelemetry metrics for client latency, server processing time, and errors via Prometheus.

The Pinecone Java SDK provides built-in support for capturing per-operation response metadata, making it straightforward to monitor your Pinecone usage with [OpenTelemetry](https://opentelemetry.io/) or any other observability system.

With this feature, you can track client-side latency, server processing time, network overhead, error rates, and more for every data plane operation your application makes.

## How it all fits together

The SDK's observability support is designed to be flexible. You don't need to adopt the entire observability stack at once -- start simple and add layers as your needs grow.

Here are the components involved and how they relate to each other:

* **Pinecone Java SDK**: Exposes a `ResponseMetadataListener` callback, a plain Java interface with no external dependencies. At its simplest, you can log the metadata to the console. No additional tools required.
* **[OpenTelemetry](https://opentelemetry.io/) (OTel)**: An open standard and SDK for producing structured telemetry data (metrics, traces, logs). If you want standardized metrics that follow [semantic conventions](https://opentelemetry.io/docs/specs/semconv/database/database-spans/), you add the OTel SDK and wire it to the listener. This is optional.
* **OTel Collector**: A vendor-neutral service that receives telemetry from your app and forwards it to a storage backend. Optional -- many setups export directly from the app to a backend.
* **Prometheus**: A time-series database that stores metrics, making them queryable over time. One popular storage option.
* **Grafana**: A visualization and dashboarding tool that queries Prometheus (or other backends) and displays charts and alerts. One popular visualization option.

A common setup chains these together:

```
Your App (OTel SDK) → OTel Collector → Prometheus (storage) → Grafana (visualization)
```

<Note>
  This is just one example pipeline. You can substitute Datadog, New Relic, or any OTel-compatible backend. You can also skip OTel entirely and use [Micrometer](#example-micrometerprometheus), custom logging, or any approach that suits your stack.
</Note>

## Response metadata listener

The Java SDK captures response metadata through a `ResponseMetadataListener` -- a functional interface you provide when building the Pinecone client. The listener is called after each data plane operation completes (whether it succeeds or fails), and receives a `ResponseMetadata` object containing timing, status, and context information.

The SDK itself has no OpenTelemetry dependency. You bring your own observability library and decide what to do with the metadata.

### Supported operations

The following data plane operations are instrumented, for both synchronous (`Index`) and asynchronous (`AsyncIndex`) usage:

| Operation | Description                |
| --------- | -------------------------- |
| `upsert`  | Insert or update vectors   |
| `query`   | Search for similar vectors |
| `fetch`   | Retrieve vectors by ID     |
| `update`  | Update vector metadata     |
| `delete`  | Delete vectors             |

### Available metadata

Each `ResponseMetadata` object provides the following fields:

| Method                   | Description                                        | OTel attribute            |
| ------------------------ | -------------------------------------------------- | ------------------------- |
| `getOperationName()`     | Operation type (e.g., `upsert`, `query`)           | `db.operation.name`       |
| `getIndexName()`         | Pinecone index name                                | `pinecone.index_name`     |
| `getNamespace()`         | Namespace (empty string if default)                | `db.namespace`            |
| `getServerAddress()`     | Pinecone server host                               | `server.address`          |
| `getClientDurationMs()`  | Total round-trip time in ms (always available)     | --                        |
| `getServerDurationMs()`  | Server processing time in ms (may be `null`)       | --                        |
| `getNetworkOverheadMs()` | Client minus server duration in ms (may be `null`) | --                        |
| `getStatus()`            | `"success"` or `"error"`                           | `status`                  |
| `getGrpcStatusCode()`    | Raw gRPC status code (e.g., `OK`, `UNAVAILABLE`)   | `db.response.status_code` |
| `getErrorType()`         | Error category, or `null` if successful            | `error.type`              |

Possible `errorType` values: `validation`, `connection`, `server`, `rate_limit`, `timeout`, `auth`, `not_found`, `unknown`.

### Recommended metrics

If you're recording OTel metrics, the SDK example project uses these metric names, which follow [OTel semantic conventions for database clients](https://opentelemetry.io/docs/specs/semconv/database/database-spans/):

| Metric                                | Type      | Unit | Description                     |
| ------------------------------------- | --------- | ---- | ------------------------------- |
| `db.client.operation.duration`        | Histogram | ms   | Client-measured round-trip time |
| `pinecone.server.processing.duration` | Histogram | ms   | Server processing time          |
| `db.client.operation.count`           | Counter   | --   | Total number of operations      |

## Quick start: Simple logging

The simplest way to use the listener is to log the metadata directly. This requires no additional dependencies beyond the Pinecone SDK:

```java theme={null}
import io.pinecone.clients.Pinecone;

Pinecone client = new Pinecone.Builder("PINECONE_API_KEY")
    .withResponseMetadataListener(metadata -> {
        System.out.printf("Operation: %s | Client: %dms | Server: %sms | Network: %sms | Status: %s%n",
            metadata.getOperationName(),
            metadata.getClientDurationMs(),
            metadata.getServerDurationMs(),
            metadata.getNetworkOverheadMs(),
            metadata.getStatus());
    })
    .build();
```

Once configured, every data plane operation automatically triggers the listener:

```java theme={null}
Index index = client.getIndexConnection("my-index");
index.upsert("id-1", Arrays.asList(0.1f, 0.2f, 0.3f));
// Output: Operation: upsert | Client: 47ms | Server: 40ms | Network: 7ms | Status: success
```

## Quick start: OpenTelemetry integration

To record structured metrics with OpenTelemetry, add the OTel SDK dependencies and wire a metrics recorder to the listener.

### 1. Add dependencies

Add the following to your `pom.xml`:

```xml theme={null}
<dependencies>
    <!-- Pinecone SDK -->
    <dependency>
        <groupId>io.pinecone</groupId>
        <artifactId>pinecone-client</artifactId>
        <version>LATEST</version>
    </dependency>

    <!-- OpenTelemetry SDK -->
    <dependency>
        <groupId>io.opentelemetry</groupId>
        <artifactId>opentelemetry-sdk</artifactId>
    </dependency>
    <dependency>
        <groupId>io.opentelemetry</groupId>
        <artifactId>opentelemetry-sdk-metrics</artifactId>
    </dependency>

    <!-- OTLP exporter (sends metrics to an OTel Collector or compatible backend) -->
    <dependency>
        <groupId>io.opentelemetry</groupId>
        <artifactId>opentelemetry-exporter-otlp</artifactId>
    </dependency>
</dependencies>

<!-- Use the OTel BOM to manage versions -->
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.opentelemetry</groupId>
            <artifactId>opentelemetry-bom</artifactId>
            <version>1.35.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
```

### 2. Create a metrics recorder

The SDK's [example project](https://github.com/pinecone-io/pinecone-java-client/tree/main/examples/java-otel-metrics) includes a reusable `PineconeMetricsRecorder` class you can copy into your project. It implements `ResponseMetadataListener` and records all three recommended metrics with proper OTel attributes:

```java theme={null}
import io.opentelemetry.api.common.AttributeKey;
import io.opentelemetry.api.common.Attributes;
import io.opentelemetry.api.common.AttributesBuilder;
import io.opentelemetry.api.metrics.LongCounter;
import io.opentelemetry.api.metrics.LongHistogram;
import io.opentelemetry.api.metrics.Meter;
import io.pinecone.configs.ResponseMetadata;
import io.pinecone.configs.ResponseMetadataListener;

public class PineconeMetricsRecorder implements ResponseMetadataListener {

    private static final AttributeKey<String> DB_SYSTEM = AttributeKey.stringKey("db.system");
    private static final AttributeKey<String> DB_OPERATION_NAME = AttributeKey.stringKey("db.operation.name");
    private static final AttributeKey<String> DB_NAMESPACE = AttributeKey.stringKey("db.namespace");
    private static final AttributeKey<String> PINECONE_INDEX_NAME = AttributeKey.stringKey("pinecone.index_name");
    private static final AttributeKey<String> SERVER_ADDRESS = AttributeKey.stringKey("server.address");
    private static final AttributeKey<String> STATUS = AttributeKey.stringKey("status");
    private static final AttributeKey<String> ERROR_TYPE = AttributeKey.stringKey("error.type");

    private final LongHistogram clientDurationHistogram;
    private final LongHistogram serverDurationHistogram;
    private final LongCounter operationCounter;

    public PineconeMetricsRecorder(Meter meter) {
        this.clientDurationHistogram = meter.histogramBuilder("db.client.operation.duration")
                .setDescription("Duration of Pinecone operations from client perspective")
                .setUnit("ms")
                .ofLongs()
                .build();

        this.serverDurationHistogram = meter.histogramBuilder("pinecone.server.processing.duration")
                .setDescription("Server processing time from x-pinecone-response-duration-ms header")
                .setUnit("ms")
                .ofLongs()
                .build();

        this.operationCounter = meter.counterBuilder("db.client.operation.count")
                .setDescription("Total number of Pinecone operations")
                .setUnit("{operation}")
                .build();
    }

    @Override
    public void onResponse(ResponseMetadata metadata) {
        AttributesBuilder attributesBuilder = Attributes.builder()
                .put(DB_SYSTEM, "pinecone")
                .put(DB_OPERATION_NAME, metadata.getOperationName())
                .put(PINECONE_INDEX_NAME, metadata.getIndexName())
                .put(SERVER_ADDRESS, metadata.getServerAddress())
                .put(STATUS, metadata.getStatus());

        String namespace = metadata.getNamespace();
        if (namespace != null && !namespace.isEmpty()) {
            attributesBuilder.put(DB_NAMESPACE, namespace);
        }

        if (!metadata.isSuccess() && metadata.getErrorType() != null) {
            attributesBuilder.put(ERROR_TYPE, metadata.getErrorType());
        }

        Attributes attributes = attributesBuilder.build();

        clientDurationHistogram.record(metadata.getClientDurationMs(), attributes);

        Long serverDuration = metadata.getServerDurationMs();
        if (serverDuration != null) {
            serverDurationHistogram.record(serverDuration, attributes);
        }

        operationCounter.add(1, attributes);
    }
}
```

### 3. Wire it into the Pinecone client

Initialize the OTel SDK, create the recorder, and pass it to the Pinecone client builder:

```java theme={null}
import io.opentelemetry.api.metrics.Meter;
import io.opentelemetry.sdk.OpenTelemetrySdk;
import io.opentelemetry.sdk.metrics.SdkMeterProvider;
import io.opentelemetry.sdk.metrics.export.PeriodicMetricReader;
import io.opentelemetry.exporter.otlp.metrics.OtlpGrpcMetricExporter;
import io.pinecone.clients.Pinecone;

// Set up OTel with OTLP exporter
OtlpGrpcMetricExporter exporter = OtlpGrpcMetricExporter.builder()
    .setEndpoint("http://localhost:4317")
    .build();

SdkMeterProvider meterProvider = SdkMeterProvider.builder()
    .registerMetricReader(PeriodicMetricReader.builder(exporter).build())
    .build();

OpenTelemetrySdk openTelemetry = OpenTelemetrySdk.builder()
    .setMeterProvider(meterProvider)
    .build();

// Create the metrics recorder
Meter meter = openTelemetry.getMeter("pinecone.client");
PineconeMetricsRecorder recorder = new PineconeMetricsRecorder(meter);

// Build the Pinecone client with the recorder
Pinecone client = new Pinecone.Builder("PINECONE_API_KEY")
    .withResponseMetadataListener(recorder)
    .build();

// Use the client normally -- metrics are recorded automatically
Index index = client.getIndexConnection("my-index");
index.upsert("id-1", Arrays.asList(0.1f, 0.2f, 0.3f));
index.query(3, Arrays.asList(0.1f, 0.2f, 0.3f));
```

<Tip>
  For a complete runnable example with Docker Compose, Prometheus, and Grafana, see the [java-otel-metrics example project](https://github.com/pinecone-io/pinecone-java-client/tree/main/examples/java-otel-metrics) in the SDK repository.
</Tip>

## Example: Micrometer/Prometheus

If your application uses [Micrometer](https://micrometer.io/) (common in Spring Boot), you can wire the listener to Micrometer instead of the OTel SDK:

```java theme={null}
import io.micrometer.core.instrument.MeterRegistry;
import io.micrometer.core.instrument.Timer;
import io.pinecone.clients.Pinecone;
import java.util.concurrent.TimeUnit;

Pinecone client = new Pinecone.Builder("PINECONE_API_KEY")
    .withResponseMetadataListener(metadata -> {
        Timer.builder("pinecone.client.duration")
            .tag("operation", metadata.getOperationName())
            .tag("index", metadata.getIndexName())
            .tag("status", metadata.getStatus())
            .register(meterRegistry)
            .record(metadata.getClientDurationMs(), TimeUnit.MILLISECONDS);
    })
    .build();
```

## Visualizing metrics

Once your metrics are flowing to a backend, you can build dashboards to monitor your Pinecone operations. If you're using Prometheus and Grafana, here are some useful queries:

**P50 and P95 client latency:**

```promql theme={null}
histogram_quantile(0.5, sum(rate(db_client_operation_duration_milliseconds_bucket[5m])) by (le))
histogram_quantile(0.95, sum(rate(db_client_operation_duration_milliseconds_bucket[5m])) by (le))
```

**P95 latency by operation type:**

```promql theme={null}
histogram_quantile(0.95, sum(rate(db_client_operation_duration_milliseconds_bucket[5m])) by (le, db_operation_name))
```

**Operation count by type:**

```promql theme={null}
sum by (db_operation_name) (db_client_operation_count_total)
```

## Understanding the latency breakdown

The `ResponseMetadata` object provides three timing values that help you pinpoint the source of latency issues:

| Component        | Method                   | What it measures                                                                                                                             |
| ---------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| Client duration  | `getClientDurationMs()`  | Total round-trip time from request start to response completion. Always available.                                                           |
| Server duration  | `getServerDurationMs()`  | Time the Pinecone backend spent processing the request. Extracted from the `x-pinecone-response-duration-ms` response header. May be `null`. |
| Network overhead | `getNetworkOverheadMs()` | The difference: client duration minus server duration. Includes network latency, serialization, and deserialization. May be `null`.          |

Use these values to diagnose performance issues:

* **High server duration**: The bottleneck is on the Pinecone backend. Consider optimizing your query (e.g., reducing `topK`, using metadata filters), or check the [Pinecone status page](https://status.pinecone.io/).
* **High network overhead**: The bottleneck is in the network path between your application and Pinecone. Consider deploying your application closer to your index's cloud region, or check for network issues.

## Limitations

* **Data plane operations only.** Control plane operations (e.g., creating or deleting indexes) are not currently instrumented.
* **Bulk import operations** are not yet instrumented.
* **Server duration may be unavailable.** The `getServerDurationMs()` method returns `null` if the `x-pinecone-response-duration-ms` header is not present in the response.
* **Synchronous callback.** The listener is called synchronously after the gRPC response is received. Keep implementations lightweight and non-blocking to avoid adding latency to your operations. For heavy processing, queue the metadata for async handling.
* **Exceptions are swallowed.** Exceptions thrown by the listener are logged but do not affect the operation result.

## Best practices

* **Keep listeners lightweight.** Record metrics or enqueue work -- don't do I/O or heavy computation in the callback.
* **Follow OTel semantic conventions.** Use the attribute names shown in the [recommended metrics](#recommended-metrics) table for interoperability with standard dashboards and tooling.
* **Monitor both client and server duration.** Tracking both lets you separate Pinecone backend performance from network conditions.
* **Set alerts on error rates.** Use the `status` and `error.type` attributes to build alerts for elevated error rates across operations.


# Pinecone Java SDK
Source: https://docs.pinecone.io/reference/sdks/java/overview

Install and use the Pinecone Java SDK to manage indexes and namespaces, upsert vectors, run semantic search, and call the Admin and Inference APIs from Java.

<Tip>
  For installation instructions and usage examples, see the [Pinecone Java SDK documentation](https://github.com/pinecone-io/pinecone-java-client). To report an issue or request a feature, [file an issue on GitHub](https://github.com/pinecone-io/pinecone-java-client/issues).
</Tip>

## Requirements

The Pinecone Java SDK requires Java 1.8 or later.

## SDK versions

SDK versions are pinned to specific [API versions](/reference/api/versioning). When a new API version is released, a new version of the SDK is also released.

The mappings between API versions and Java SDK versions are as follows:

| API version | SDK version |
| :---------- | :---------- |
| `2025-04`   | v5.x        |
| `2025-01`   | v4.x        |
| `2024-10`   | v3.x        |
| `2024-07`   | v2.x        |
| `2024-04`   | v1.x        |

When a new stable API version is released, you should upgrade your SDK to the latest version to ensure compatibility with the latest API changes.

## Install

To install the latest version of the [Java SDK](https://github.com/pinecone-io/pinecone-java-client), add a dependency to the current module:

```shell Java theme={null}
# Maven
<dependency>
  <groupId>io.pinecone</groupId>
  <artifactId>pinecone-client</artifactId>
  <version>5.0.0</version>
</dependency>

# Gradle
implementation "io.pinecone:pinecone-client:5.0.0"
```

Alternatively, you can download the standalone uberjar [pinecone-client-4.0.0-all.jar](https://repo1.maven.org/maven2/io/pinecone/pinecone-client/4.0.0/pinecone-client-4.0.0-all.jar), which bundles the Pinecone SDK and all dependencies together. You can include this in your classpath like you do with any third-party JAR without having to obtain the `pinecone-client` dependencies separately.

## Upgrade

<Warning>
  Before upgrading to `v4.0.0`, update all relevant code to account for the breaking changes explained [here](/release-notes/2025#2025-02-07-3).
</Warning>

If you are already using the Java SDK, upgrade the dependency in the current module to the latest version:

```shell Java theme={null}
# Maven
<dependency>
  <groupId>io.pinecone</groupId>
  <artifactId>pinecone-client</artifactId>
  <version>5.0.0</version>
</dependency>

# Gradle
implementation "io.pinecone:pinecone-client:5.0.0"
```

## Initialize

Once installed, you can import the SDK and then use an [API key](/guides/production/security-overview#api-keys) to initialize a client instance:

```Java theme={null}
import io.pinecone.clients.Pinecone;
import org.openapitools.db_control.client.model.*;

public class InitializeClientExample {
    public static void main(String[] args) {
        Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build();
    }
}
```

## Observability

The Java SDK supports capturing per-operation response metadata for all data plane operations, including client-side latency, server processing time, network overhead, and error details. You can use this metadata with [OpenTelemetry](https://opentelemetry.io/), Micrometer, or any other observability system to monitor your Pinecone usage in production.

For setup instructions and examples, see [OpenTelemetry support](/reference/sdks/java/open-telemetry).


# Reference
Source: https://docs.pinecone.io/reference/sdks/java/reference

Reference documentation for the Pinecone Java SDK, including client setup, types, and methods for managing indexes and vector data operations.



# Pinecone Node.js SDK
Source: https://docs.pinecone.io/reference/sdks/node/overview

Install and use the Pinecone Node.js and TypeScript SDK to manage indexes, upsert vectors, run semantic search, and call the Admin and Inference APIs.

<Tip>
  For installation instructions, usage examples, and reference information, see the [Pinecone Node.js SDK documentation](https://sdk.pinecone.io/typescript/). To report an issue or request a feature, [file an issue on GitHub](https://github.com/pinecone-io/pinecone-ts-client/issues).
</Tip>

## Requirements

The Pinecone Node SDK requires TypeScript 4.1 or later and Node 18.x or later.

## SDK versions

SDK versions are pinned to specific [API versions](/reference/api/versioning). When a new API version is released, a new version of the SDK is also released.

The mappings between API versions and Node.js SDK versions are as follows:

| API version | SDK version |
| :---------- | :---------- |
| `2026-04`   | v8.x        |
| `2025-10`   | v7.x        |
| `2025-04`   | v6.x        |
| `2025-01`   | v5.x        |
| `2024-10`   | v4.x        |
| `2024-07`   | v3.x        |
| `2024-04`   | v2.x        |

When a new stable API version is released, you should upgrade your SDK to the latest version to ensure compatibility with the latest API changes.

## Install

To install the latest version of the [Node.js SDK](https://github.com/pinecone-io/pinecone-ts-client), written in TypeScript, run the following command:

```Shell theme={null}
npm install @pinecone-database/pinecone
```

To check your SDK version, run the following command:

```Shell theme={null}
npm list | grep @pinecone-database/pinecone
```

## Upgrade

If you already have the Node.js SDK, upgrade to the latest version as follows:

```Shell theme={null}
npm install @pinecone-database/pinecone@latest
```

## Initialize

Once installed, you can import the library and then use an [API key](/guides/projects/manage-api-keys) to initialize a client instance:

```JavaScript theme={null}
import { Pinecone } from '@pinecone-database/pinecone';

const pc = new Pinecone({
    apiKey: 'YOUR_API_KEY'
});
```

To manage organizations, projects, API keys, and [role-based access control](/guides/production/manage-rbac), initialize an `AdminClient` with [service account](/guides/organizations/manage-service-accounts) credentials instead. This requires v8.2.0 or later:

```JavaScript theme={null}
import { AdminClient } from '@pinecone-database/pinecone';

// Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
const admin = new AdminClient();
```

You can also pass `clientId` and `clientSecret` directly to the constructor instead of setting environment variables.

## Proxy configuration

If your network setup requires you to interact with Pinecone through a proxy, you can pass a custom `ProxyAgent` from the [`undici` library](https://undici.nodejs.org/#/). Below is an example of how to construct an `undici` `ProxyAgent` that routes network traffic through a [`mitm` proxy server](https://mitmproxy.org/) while hitting Pinecone's `/indexes` endpoint.

<Note>
  The following strategy relies on Node's native [`fetch`](https://nodejs.org/docs/latest/api/globals.html#fetch) implementation, released in Node v16 and stabilized in Node v21. If you are running Node versions 18-21, you may experience issues stemming from the instability of the feature. There are currently no known issues related to proxying in Node v18+.
</Note>

```JavaScript JavaScript theme={null}
import {
  Pinecone,
  type PineconeConfiguration,
} from '@pinecone-database/pinecone';
import { Dispatcher, ProxyAgent } from 'undici';
import * as fs from 'fs';

const cert = fs.readFileSync('path/to/mitmproxy-ca-cert.pem');

const client = new ProxyAgent({
  uri: 'https://your-proxy.com',
  requestTls: {
    port: 'YOUR_PROXY_SERVER_PORT',
    ca: cert,
    host: 'YOUR_PROXY_SERVER_HOST',
  },
});

const customFetch = (
  input: string | URL | Request,
  init: RequestInit | undefined
) => {
  return fetch(input, {
    ...init,
    dispatcher: client as Dispatcher,
    keepalive: true,  # optional
  });
};

const config: PineconeConfiguration = {
  apiKey:
    'YOUR_API_KEY',
  fetchApi: customFetch,
};

const pc = new Pinecone(config);

const indexes = async () => {
  return await pc.listIndexes();
};

indexes().then((response) => {
  console.log('My indexes: ', response);
});
```


# Reference
Source: https://docs.pinecone.io/reference/sdks/node/reference

Reference documentation for the Pinecone Node.js SDK, including client setup, types, and methods for managing indexes and vector data operations.



# Pinecone Python SDK
Source: https://docs.pinecone.io/reference/sdks/python/overview

Install and use the Pinecone SDK for Pinecone Python SDK: auth, typed clients, and API operations. For installation instructions, usage examples, and.

<Tip>
  For installation instructions, usage examples, and reference information, see the [Pinecone Python SDK documentation](https://sdk.pinecone.io/python/). To report an issue or request a feature, [file an issue on GitHub](https://github.com/pinecone-io/pinecone-python-client/issues).
</Tip>

The Pinecone Python SDK is distributed on PyPI using the package name `pinecone`. By default, the `pinecone` package has a minimal set of dependencies and interacts with Pinecone via HTTP requests. However, you can install the following extras to unlock additional functionality:

* `pinecone[grpc]` adds dependencies on `grpcio` and related libraries needed to run data operations such as upserts and queries over [gRPC](https://grpc.io/) for a modest performance improvement.

* `pinecone[asyncio]` adds a dependency on `aiohttp` and enables usage of `async` methods for use with [asyncio](https://docs.python.org/3/library/asyncio.html). For more details, see [Async requests](#async-requests).

## Requirements

The Pinecone Python SDK requires Python 3.9 or later. It has been tested with CPython versions from 3.9 to 3.13.

## SDK versions

SDK versions are pinned to specific [API versions](/reference/api/versioning). When a new API version is released, a new version of the SDK is also released.

The mappings between API versions and Python SDK versions are as follows:

| API version | SDK version   |
| :---------- | :------------ |
| `2025-04`   | v7.x          |
| `2025-01`   | v6.x          |
| `2024-10`   | v5.3.x        |
| `2024-07`   | v5.0.x-v5.2.x |
| `2024-04`   | v4.x          |

When a new stable API version is released, you should upgrade your SDK to the latest version to ensure compatibility with the latest API changes.

## Install

To install the latest version of the [Python SDK](https://github.com/pinecone-io/pinecone-python-client), run the following command:

```shell theme={null}
# Install the latest version
pip install pinecone

# Install the latest version with gRPC extras
pip install "pinecone[grpc]"

# Install the latest version with asyncio extras
pip install "pinecone[asyncio]"
```

To install a specific version of the Python SDK, run the following command:

```shell pip theme={null}
# Install a specific version
pip install pinecone==<version>

# Install a specific version with gRPC extras
pip install "pinecone[grpc]"==<version>

# Install a specific version with asyncio extras
pip install "pinecone[asyncio]"==<version>
```

To check your SDK version, run the following command:

```shell pip theme={null}
pip show pinecone
```

<Note>
  To use the [Inference API](/reference/api/introduction#inference), you must be on version 5.0.0 or later.
</Note>

### Install the Pinecone Assistant Python plugin

As of Python SDK v7.0.0, the `pinecone-plugin-assistant` package is included by default. It is only necessary to install the package if you are using a version of the Python SDK prior to v7.0.0.

```shell HTTP theme={null}
pip install --upgrade pinecone pinecone-plugin-assistant
```

## Upgrade

<Warning>
  Before upgrading to `v6.0.0`, update all relevant code to account for the breaking changes explained [here](https://github.com/pinecone-io/pinecone-python-client/blob/main/docs/upgrading.md).

  Also, make sure to upgrade using the `pinecone` package name instead of `pinecone-client`; upgrading with the latter will not work as of `v6.0.0`.
</Warning>

If you already have the Python SDK, upgrade to the latest version as follows:

```shell theme={null}
# Upgrade to the latest version
pip install pinecone --upgrade

# Upgrade to the latest version with gRPC extras
pip install "pinecone[grpc]" --upgrade

# Upgrade to the latest version with asyncio extras
pip install "pinecone[asyncio]" --upgrade
```

## Initialize

Once installed, you can import the library and then use an [API key](/guides/projects/manage-api-keys) to initialize a client instance:

<CodeGroup>
  ```Python HTTP theme={null}
  from pinecone import Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")
  ```

  ```python gRPC theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")
  ```
</CodeGroup>

When [creating an index](/guides/index-data/create-an-index), import the `ServerlessSpec` or `PodSpec` class as well:

<CodeGroup>
  ```Python Serverless index theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone
  from pinecone import ServerlessSpec

  pc = Pinecone(api_key="YOUR_API_KEY")

  pc.create_index(
    name="docs-example",
    dimension=1536,
    metric="cosine",
    spec=ServerlessSpec(
      cloud="aws",
      region="us-east-1"
    )
  )
  ```

  ```Python Pod-based index theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone
  from pinecone import PodSpec

  pc = Pinecone(api_key="YOUR_API_KEY")

  pc.create_index(
    name="docs-example",
    dimension=1536,
    metric="cosine",
    spec=PodSpec(
      environment="us-west-1-gcp",
      pod_type="p1.x1",
      pods=1
    )
  )
  ```
</CodeGroup>

## Proxy configuration

If your network setup requires you to interact with Pinecone through a proxy, you will need to pass additional configuration using optional keyword parameters:

* `proxy_url`: The location of your proxy. This could be an HTTP or HTTPS URL depending on your proxy setup.
* `proxy_headers`: Accepts a python dictionary which can be used to pass any custom headers required by your proxy. If your proxy is protected by authentication, use this parameter to pass basic authentication headers with a digest of your username and password. The `make_headers` utility from `urllib3` can be used to help construct the dictionary. **Note:** Not supported with Asyncio.
* `ssl_ca_certs`: By default, the client will perform SSL certificate verification using the CA bundle maintained by Mozilla in the [`certifi`](https://pypi.org/project/certifi/) package. If your proxy is using self-signed certicates, use this parameter to specify the path to the certificate (PEM format).
* `ssl_verify`: SSL verification is enabled by default, but it is disabled when set to `False`. It is not recommened to go into production with SSL verification disabled.

<CodeGroup>
  ```python HTTP theme={null}
  from pinecone import Pinecone
  import urllib3
  from urllib3.util import make_headers

  pc = Pinecone(
      api_key="YOUR_API_KEY",
      proxy_url='https://your-proxy.com',
      proxy_headers=make_headers(proxy_basic_auth='username:password'),
      ssl_ca_certs='path/to/cert-bundle.pem'
  )
  ```

  ```python gRPC theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone
  import urllib3
  from urllib3.util import make_headers

  pc = Pinecone(
      api_key="YOUR_API_KEY",
      proxy_url='https://your-proxy.com',
      proxy_headers=make_headers(proxy_basic_auth='username:password'),
      ssl_ca_certs='path/to/cert-bundle.pem'
  )
  ```

  ```python asyncio theme={null}
  import asyncio
  from pinecone import PineconeAsyncio
  	
  async def main():
      async with PineconeAsyncio(
          api_key="YOUR_API_KEY",
          proxy_url='https://your-proxy.com',
          ssl_ca_certs='path/to/cert-bundle.pem'
      ) as pc:
          # Do async things
          await pc.list_indexes()

  asyncio.run(main())
  ```
</CodeGroup>

## Async requests

Pinecone Python SDK versions 6.0.0 and later provide `async` methods for use with [asyncio](https://docs.python.org/3/library/asyncio.html). Asyncio support makes it possible to use Pinecone with modern async web frameworks such as [FastAPI](https://fastapi.tiangolo.com/), [Quart](https://quart.palletsprojects.com/en/latest/), and [Sanic](https://sanic.dev/en/), and should significantly increase the efficiency of running requests in parallel.

Use the [`PineconeAsyncio`](https://sdk.pinecone.io/python/asyncio.html) class to create and manage indexes and the [`IndexAsyncio`](https://sdk.pinecone.io/python/asyncio.html#pinecone.db_data.IndexAsyncio) class to read and write index data. To ensure that sessions are properly closed, use the `async with` syntax when creating `PineconeAsyncio` and `IndexAsyncio` objects.

<CodeGroup>
  ```python Manage indexes theme={null}
  # pip install "pinecone[asyncio]"
  import asyncio
  from pinecone import PineconeAsyncio, ServerlessSpec

  async def main():
      async with PineconeAsyncio(api_key="YOUR_API_KEY") as pc:
          if not await pc.has_index(index_name):
              desc = await pc.create_index(
                  name="docs-example",
                  dimension=1536,
                  metric="cosine",
                  spec=ServerlessSpec(
                      cloud="aws",
                      region="us-east-1"
                  ),
                  deletion_protection="disabled",
                  tags={
                      "environment": "development"
                  }
              )

  asyncio.run(main())
  ```

  ```python Read and write index data theme={null}
  # pip install "pinecone[asyncio]"
  import asyncio
  from pinecone import Pinecone

  async def main():
      pc = Pinecone(api_key="YOUR_API_KEY")
      async with pc.IndexAsyncio(host="INDEX_HOST") as idx:
          await idx.upsert_records(
              namespace="example-namespace",
              records=[
                  {
                      "id": "1",
                      "title": "The Great Gatsby",
                      "author": "F. Scott Fitzgerald",
                      "description": "The story of the mysteriously wealthy Jay Gatsby and his love for the beautiful Daisy Buchanan.",
                      "year": 1925,
                  },
                  {
                      "id": "2",
                      "title": "To Kill a Mockingbird",
                      "author": "Harper Lee",
                      "description": "A young girl comes of age in the segregated American South and witnesses her father's courageous defense of an innocent black man.",
                      "year": 1960,
                  },
                  {
                      "id": "3",
                      "title": "1984",
                      "author": "George Orwell",
                      "description": "In a dystopian future, a totalitarian regime exercises absolute control through pervasive surveillance and propaganda.",
                      "year": 1949,
                  },
              ]
          )

  asyncio.run(main())
  ```
</CodeGroup>

## Query across namespaces

Each query is limited to a single [namespace](/guides/index-data/indexing-overview#namespaces). However, the Pinecone Python SDK provides a `query_namespaces` utility method to run a query in parallel across multiple namespaces in an index and then merge the result sets into a single ranked result set with the `top_k` most relevant results.

The `query_namespaces` method accepts most of the same arguments as `query` with the addition of a required `namespaces` parameter.

<Tabs>
  <Tab title="Python SDK without gRPC">
    When using the Python SDK without gRPC extras, to get good performance, it is important to set values for the `pool_threads` and `connection_pool_maxsize` properties on the index client. The `pool_threads` setting is the number of threads available to execute requests, while `connection_pool_maxsize` is the number of cached http connections that will be held. Since these tasks are not computationally heavy and are mainly i/o bound, it should be okay to have a high ratio of threads to cpus.

    The combined results include the sum of all read unit usage used to perform the underlying queries for each namespace.

    ```python Python theme={null}
    from pinecone import Pinecone

    pc = Pinecone(api_key="YOUR_API_KEY")
    index = pc.Index(
        name="docs-example",
        pool_threads=50,             # <-- make sure to set these
        connection_pool_maxsize=50,  # <-- make sure to set these
    )

    query_vec = [ 0.1, ...] # an embedding vector with same dimension as the index
    combined_results = index.query_namespaces(
        vector=query_vec,
        namespaces=['ns1', 'ns2', 'ns3', 'ns4'],
        metric="cosine",
        top_k=10,
        include_values=False,
        include_metadata=True,
        filter={"genre": { "$eq": "comedy" }},
        show_progress=False,
    )

    for scored_vec in combined_results.matches:
        print(scored_vec)
    print(combined_results.usage)
    ```
  </Tab>

  <Tab title="Python SDK with gRPC">
    When using the Python SDK with gRPC extras, there is no need to set the `connection_pool_maxsize` because grpc makes efficient use of open connections by default.

    ```python Python theme={null}
    from pinecone.grpc import PineconeGRPC

    pc = PineconeGRPC(api_key="YOUR_API_KEY")
    index = pc.Index(
        name="docs-example",
        pool_threads=50, # <-- make sure to set this
    )

    query_vec = [ 0.1, ...] # an embedding vector with same dimension as the index
    combined_results = index.query_namespaces(
        vector=query_vec,
        namespaces=['ns1', 'ns2', 'ns3', 'ns4'],
        metric="cosine",
        top_k=10,
        include_values=False,
        include_metadata=True,
        filter={"genre": { "$eq": "comedy" }},
        show_progress=False,
    )

    for scored_vec in combined_results.matches:
        print(scored_vec)
    print(combined_results.usage)
    ```
  </Tab>
</Tabs>

## Upsert from a dataframe

To quickly ingest data when using the [Python SDK](/reference/sdks/python/overview), use the `upsert_from_dataframe` method. The method includes retry logic and`batch_size`, and is performant especially with Parquet file data sets.

The following example upserts the `uora_all-MiniLM-L6-bm25` dataset as a dataframe.

```Python Python theme={null}
from pinecone import Pinecone, ServerlessSpec
from pinecone_datasets import list_datasets, load_dataset

pc = Pinecone(api_key="API_KEY")

dataset = load_dataset("quora_all-MiniLM-L6-bm25")

pc.create_index(
  name="docs-example",
  dimension=384,
  metric="cosine",
  spec=ServerlessSpec(
    cloud="aws",
    region="us-east-1"
  )
)

# To get the unique host for an index, 
# see https://docs.pinecone.io/guides/manage-data/target-an-index
index = pc.Index(host="INDEX_HOST")

index.upsert_from_dataframe(dataset.drop(columns=["blob"]))
```


# Reference
Source: https://docs.pinecone.io/reference/sdks/python/reference

Reference documentation for the Pinecone Python SDK, including client setup, types, and methods for managing indexes and vector data operations.



# Spark-Pinecone connector
Source: https://docs.pinecone.io/reference/tools/pinecone-spark-connector

Pinecone data tools: Use the connector to efficiently create, ingest, and update vector embeddings at scale with Databricks and Pinecone.

Use the [`spark-pinecone` connector](https://github.com/pinecone-io/spark-pinecone/) to efficiently create, ingest, and update [vector embeddings](https://www.pinecone.io/learn/vector-embeddings/) at scale with [Databricks and Pinecone](/integrations/databricks).

## Install the Spark-Pinecone connector

<Tabs>
  <Tab title="Databricks platform">
    1. [Install the Spark-Pinecone connector as a library](https://docs.databricks.com/en/libraries/cluster-libraries.html#install-a-library-on-a-cluster).
    2. Configure the library as follows:
       1. Select **File path/S3** as the **Library Source**.

       2. Enter the S3 URI for the Pinecone assembly JAR file:

          ```
          s3://pinecone-jars/1.1.0/spark-pinecone-uberjar.jar  
          ```

          <Note>
            Databricks platform users must use the Pinecone assembly jar listed above to ensure that the proper dependecies are installed.
          </Note>

       3. Click **Install**.
  </Tab>

  <Tab title="Databricks on AWS">
    1. [Install the Spark-Pinecone connector as a library](https://docs.databricks.com/en/libraries/cluster-libraries.html#install-a-library-on-a-cluster).
    2. Configure the library as follows:
       1. Select **File path/S3** as the **Library Source**.

       2. Enter the S3 URI for the Pinecone assembly JAR file:

          ```
          s3://pinecone-jars/1.1.0/spark-pinecone-uberjar.jar  
          ```

       3. Click **Install**.
  </Tab>

  <Tab title="Databricks on GCP / Azure">
    1. [Install the Spark-Pinecone connector as a library](https://docs.databricks.com/en/libraries/cluster-libraries.html#install-a-library-on-a-cluster).
    2. Configure the library as follows:
       1. [Download the Pinecone assembly JAR file](https://repo1.maven.org/maven2/io/pinecone/spark-pinecone_2.12/1.1.0/).
       2. Select **Workspace** as the **Library Source**.
       3. Upload the JAR file.
       4. Click **Install**.
  </Tab>
</Tabs>

## Batch upsert

To batch upsert embeddings to Pinecone:

<CodeGroup>
  ```python Python theme={null}
  from pyspark import SparkConf
  from pyspark.sql import SparkSession
  from pyspark.sql.types import StructType, StructField, ArrayType, FloatType, StringType, LongType

  # Your API key and index name
  api_key = "PINECONE_API_KEY"
  index_name = "PINECONE_INDEX_NAME"
  source_tag = "PINECONE_SOURCE_TAG"

  COMMON_SCHEMA = StructType([
      StructField("id", StringType(), False),
      StructField("namespace", StringType(), True),
      StructField("values", ArrayType(FloatType(), False), False),
      StructField("metadata", StringType(), True),
      StructField("sparse_values", StructType([
          StructField("indices", ArrayType(LongType(), False), False),
          StructField("values", ArrayType(FloatType(), False), False)
      ]), True)
  ])

  # Initialize Spark
  spark = SparkSession.builder.getOrCreate()

  # Read the file and apply the schema
  df = spark.read \
      .option("multiLine", value = True) \
      .option("mode", "PERMISSIVE") \
      .schema(COMMON_SCHEMA) \
      .json("src/test/resources/sample.jsonl")

  # Show if the read was successful
  df.show()

  # Write the dataFrame to Pinecone in batches 
  df.write \
      .option("pinecone.apiKey", api_key) \
      .option("pinecone.indexName", index_name) \
      .option("pinecone.sourceTag", source_tag) \
      .format("io.pinecone.spark.pinecone.Pinecone") \
      .mode("append") \
      .save()
  ```

  ```scala Scala theme={null}
  import io.pinecone.spark.pinecone.{COMMON_SCHEMA, PineconeOptions}
  import org.apache.spark.SparkConf
  import org.apache.spark.sql.{SaveMode, SparkSession}

  object MainApp extends App {
    // Your API key and index name
    val apiKey = "PINECONE_API_KEY"
    val indexName = "PINECONE_INDEX_NAME"
    val sourceTag = "PINECONE_SOURCE_TAG"

    // Configure Spark to run locally with all available cores
    val conf = new SparkConf()
      .setMaster("local[*]")

    // Create a Spark session with the defined configuration
    val spark = SparkSession.builder().config(conf).getOrCreate()

    // Read the JSON file into a DataFrame, applying the COMMON_SCHEMA
    val df = spark.read
      .option("multiLine", value = true)
      .option("mode", "PERMISSIVE")
      .schema(COMMON_SCHEMA)
      .json("src/test/resources/sample.jsonl") // path to sample.jsonl

    // Define Pinecone options as a Map
    val pineconeOptions = Map(
      PineconeOptions.PINECONE_API_KEY_CONF -> apiKey,
      PineconeOptions.PINECONE_INDEX_NAME_CONF -> indexName,
      PineconeOptions.PINECONE_SOURCE_TAG_CONF -> sourceTag
    )

    // Show if the read was successful
    df.show(df.count().toInt)
    
    // Write the DataFrame to Pinecone using the defined options in batches
    df.write
      .options(pineconeOptions)
      .format("io.pinecone.spark.pinecone.Pinecone")
      .mode(SaveMode.Append)
      .save()
  }
  ```
</CodeGroup>

<Tip>
  For a guide on how to set up batch upserts, refer to the [Databricks integration page](/integrations/databricks#setup-guide).
</Tip>

## Stream upsert

To stream upsert embeddings to Pinecone:

<CodeGroup>
  ```python Python theme={null}
  from pyspark.sql import SparkSession
  from pyspark.sql.types import StructType, StructField, ArrayType, FloatType, StringType, LongType
  import os

  # Your API key and index name
  api_key = "PINECONE_API_KEY"
  index_name = "PINECONE_INDEX_NAME"
  source_tag = "PINECONE_SOURCE_TAG"

  COMMON_SCHEMA = StructType([
      StructField("id", StringType(), False),
      StructField("namespace", StringType(), True),
      StructField("values", ArrayType(FloatType(), False), False),
      StructField("metadata", StringType(), True),
      StructField("sparse_values", StructType([
          StructField("indices", ArrayType(LongType(), False), False),
          StructField("values", ArrayType(FloatType(), False), False)
      ]), True)
  ])

  # Initialize Spark session
  spark = SparkSession.builder \
      .appName("StreamUpsertExample") \
      .config("spark.sql.shuffle.partitions", 3) \
      .master("local") \
      .getOrCreate()

  # Read the stream of JSON files, applying the schema from the input directory
  lines = spark.readStream \
      .option("multiLine", True) \
      .option("mode", "PERMISSIVE") \
      .schema(COMMON_SCHEMA) \
      .json("path/to/input/directory/")

  # Write the stream to Pinecone using the defined options
  upsert = lines.writeStream \
      .format("io.pinecone.spark.pinecone.Pinecone") \
      .option("pinecone.apiKey", api_key) \
      .option("pinecone.indexName", index_name) \
      .option("pinecone.sourceTag", source_tag) \
      .option("checkpointLocation", "path/to/checkpoint/dir") \
      .outputMode("append") \
      .start()

  upsert.awaitTermination()
  ```

  ```scala Scala theme={null}
  import io.pinecone.spark.pinecone.{COMMON_SCHEMA, PineconeOptions}
  import org.apache.spark.SparkConf
  import org.apache.spark.sql.{SaveMode, SparkSession}

  object MainApp extends App {
    // Your API key and index name
    val apiKey = "PINECONE_API_KEY"
    val indexName = "PINECONE_INDEX_NAME"

    // Create a Spark session
    val spark = SparkSession.builder()
      .appName("StreamUpsertExample")
      .config("spark.sql.shuffle.partitions", 3)
      .master("local")
      .getOrCreate()

    // Read the JSON files into a DataFrame, applying the COMMON_SCHEMA from input directory
    val lines = spark.readStream
      .option("multiLine", value = true)
      .option("mode", "PERMISSIVE")
      .schema(COMMON_SCHEMA)
      .json("path/to/input/directory/")

    // Define Pinecone options as a Map
    val pineconeOptions = Map(
      PineconeOptions.PINECONE_API_KEY_CONF -> System.getenv("PINECONE_API_KEY"),
      PineconeOptions.PINECONE_INDEX_NAME_CONF -> System.getenv("PINECONE_INDEX"),
      PineconeOptions.PINECONE_SOURCE_TAG_CONF -> System.getenv("PINECONE_SOURCE_TAG")
    )

    // Write the stream to Pinecone using the defined options
    val upsert = lines
      .writeStream
      .format("io.pinecone.spark.pinecone.Pinecone")
      .options(pineconeOptions)
      .option("checkpointLocation", "path/to/checkpoint/dir")
      .outputMode("append")
      .start()

    upsert.awaitTermination()
  }
  ```
</CodeGroup>

## Learn more

* [Spark-Pinecone connector setup guide](/integrations/databricks#setup-guide)
* [GitHub](https://github.com/pinecone-io/spark-pinecone)


# Authentication
Source: https://docs.pinecone.io/reference/api/authentication

Pinecone API authentication guide covering API key generation, SDK client setup, and HTTP header configuration for authorized requests.

All requests to [Pinecone APIs](/reference/api/introduction) must contain a valid [API key](/guides/production/security-overview#api-keys) for the target project.

## Get an API key

[Create a new API key](https://app.pinecone.io/organizations/-/projects/-/keys) in the Pinecone console, or use the connect widget below to generate a key.

<div>
  <div>
    <div>
      <div />
    </div>
  </div>
</div>

Copy your generated key:

```
PINECONE_API_KEY="{{YOUR_API_KEY}}"

# This API key has ReadWrite access to all indexes in your project.
```

## Initialize a client

When using a [Pinecone SDK](/reference/pinecone-sdks), initialize a client object with your API key and then reuse the authenicated client in subsquent function calls. For example:

<CodeGroup>
  ```Python Python theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone
  from pinecone import ServerlessSpec

  pc = Pinecone(api_key='YOUR_API_KEY')

  # Creates an index using the API key stored in the client 'pc'.
  pc.create_index(
      name="docs-example",
      dimension=1536,
      metric="cosine",
      spec=ServerlessSpec(
          cloud='aws', 
          region='us-east-1'
      ) 
  ) 
  ```

  ```JavaScript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone';

  const pc = new Pinecone({
      apiKey: 'YOUR_API_KEY' 
  });

  // Creates an index using the API key stored in the client 'pc'.
  await pc.createIndex({
      name: 'docs-example',
      dimension: 1536,
      metric: 'cosine',
      spec: { 
          serverless: { 
              cloud: 'aws', 
              region: 'us-east-1' 
          }
      } 
  }) 
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Pinecone;
  import org.openapitools.db_control.client.model.IndexModel;
  import org.openapitools.db_control.client.model.DeletionProtection;

  public class CreateServerlessIndexExample {
      public static void main(String[] args) {
          Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build();

          // Creates an index using the API key stored in the client 'pc'.
          pc.createServerlessIndex("docs-example", "cosine", 1536, "aws", "us-east-1");
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "fmt"
      "log"

      "github.com/pinecone-io/go-pinecone/v3/pinecone"
  )

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

  	indexName := "docs-example"
  	vectorType := "dense"
      dimension := int32(1536)
      metric := pinecone.Cosine
  	deletionProtection := pinecone.DeletionProtectionDisabled

      idx, err := pc.CreateServerlessIndex(ctx, &pinecone.CreateServerlessIndexRequest{
          Name:               indexName,
          VectorType:         &vectorType,
          Dimension:          &dimension,
          Metric:             &metric,
          Cloud:              pinecone.Aws,
          Region:             "us-east-1",
          DeletionProtection: &deletionProtection,
      })
      if err != nil {
          log.Fatalf("Failed to create serverless index: %v", err)
      } else {
          fmt.Printf("Successfully created serverless index: %v", idx.Name)
      }
  }
  ```

  ```shell curl theme={null}
  curl -s "https://api.pinecone.io/indexes" \
      -H "Api-Key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -H "X-Pinecone-Api-Version: 2025-10" \
      -d '{
          "name":  "docs-example",
          "dimension": 1536,
          "metric": "cosine",
          "spec": {
              "serverless": {
                 "cloud":"aws",
                 "region": "us-east-1"
              }
          }
      }'
  ```
</CodeGroup>

## Add headers to an HTTP request

All HTTP requests to Pinecone APIs must contain an `Api-Key` header that specifies a valid [API key](/guides/production/security-overview#api-keys) and must be encoded as JSON with the `Content-Type: application/json` header. For example:

```shell curl theme={null}
curl https://api.pinecone.io/indexes \
   -H "Content-Type: application/json" \
   -H "Api-Key: $PINECONE_API_KEY" \
  -H "X-Pinecone-Api-Version: 2025-10" \
   -d '{
         "name":  "docs-example",
         "dimension": 1536,
         "metric": "cosine",
         "spec": {
            "serverless": {
               "cloud":"aws",
               "region": "us-east-1"
            }
         }
      }'
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Initialization errors due to outdated SDKs">
    Older versions of Pinecone required you to initialize a client with an `init` method that takes both `api_key` and `environment` parameters, for example:

    <CodeGroup>
      ```python Python theme={null}
      # Legacy initialization
      import pinecone

      pc = pinecone.init(
          api_key="PINECONE_API_KEY",
          environment="PINECONE_ENVIRONMENT"
      )
      ```

      ```javascript JavaScript theme={null}
      // Legacy initialization
      import { Pinecone } from '@pinecone-database/pinecone';

      const pineconeClient = new PineconeClient();
      await pineconeClient.init({
          apiKey: 'PINECONE_API_KEY',
          environment: 'PINECONE_ENVIRONMENT',
      });
      ```
    </CodeGroup>

    In more recent versions of Pinecone, this has changed. Initialization no longer requires an `init` step, and cloud environment is defined for each index rather than an entire project. Client initialization now only requires an `api_key` parameter, for example:

    <CodeGroup>
      ```python Python theme={null}
      # New initialization
      from pinecone import Pinecone

      pc = Pinecone(api_key="YOUR_API_KEY")
      ```

      ```javascript JavaScript theme={null}
      // New initialization
      import { Pinecone } from '@pinecone-database/pinecone';

      const pc = new Pinecone({
          apiKey: 'YOUR_API_KEY' 
      });
      ```
    </CodeGroup>

    If you are receiving errors about initialization, upgrade your [Pinecone SDK](/reference/pinecone-sdks) to the latest version, for example:

    <CodeGroup>
      ```shell Python theme={null}
      # Upgrade Pinecone SDK
      pip install pinecone --upgrade
      ```

      ```shell JavaScript theme={null}
      # Upgrade Pinecone SDK
      npm install @pinecone-database/pinecone@latest
      ```
    </CodeGroup>

    Also, note that some third-party tutorials and examples still reference the older initialization method. In such cases, follow the example above and the examples throughout the Pinecone documentation instead.
  </Accordion>
</AccordionGroup>


# Pinecone Database limits
Source: https://docs.pinecone.io/reference/api/database-limits

Reference for Pinecone Database limits, covering upsert, query, fetch, delete, import, namespace, and rate limits for serverless indexes.

This page describes different types of limits for Pinecone Database.

<Note>
  **Looking for a specific limit?**

  * To compare monthly included usage by plan, start with [read units](#read-units-per-month-per-org), [write units](#write-units-per-month-per-org), and [model usage limits](#monthly-usage-limits).
  * If you received a `429` error, check [rate limits](#rate-limits), especially request-per-second limits for query, upsert, update, delete, fetch, and list.
  * For projects, users, indexes, namespaces, storage, backups, and collections, see [object limits](#object-limits).
  * For batch sizes, metadata filters, and identifier lengths, see [operation limits](#operation-limits) and [identifier limits](#identifier-limits).
</Note>

## Rate limits

Rate limits help protect your applications from misuse and maintain the health of our shared serverless infrastructure. These limits are designed to support typical production workloads while ensuring reliable performance for all users.

**Most rate limits can be adjusted upon request.** If you need higher limits to scale your application, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) with details about your use case. Pinecone is committed to supporting your growth and can often accommodate higher throughput requirements.

Rate limits vary based on [pricing plan](https://www.pinecone.io/pricing/) and apply to [serverless indexes](/guides/index-data/indexing-overview) only.

<Note>
  Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide.
</Note>

### Data plane operations: request-per-second limits

Pinecone enforces rate limits on the number of API requests per second at the namespace level for data plane operations (query, upsert, delete, and update). These limits provide protection against excessive request rates.

#### Affected operations

The following operations are subject to request-per-second rate limiting:

| Operation | Scope         | Limit |
| --------- | ------------- | ----- |
| Query     | Per namespace | 100   |
| Upsert    | Per namespace | 100   |
| Delete    | Per namespace | 100   |
| Update    | Per namespace | 100   |

#### Error response

When you exceed the request-per-second limit, you'll receive an HTTP `429 - TOO_MANY_REQUESTS` response. The error message indicates which operation exceeded the limit and includes the namespace name and limit value. See the individual limit sections below for specific error message formats.

#### How request-per-second limits work with limits on read and write units

Request-per-second limits are enforced in addition to existing read unit and write unit limits. Requests must not exceed any applicable limits:

* Index-level limits - read and write unit limits, per index
* Namespace-level limits - read and write unit limits, per namespace
* Request-per-second limits - requests per second, per namespace

If any limit is exceeded, the request fails with a 429 error.

#### Recommendations

If you're hitting request-per-second limits:

1. Implement retry logic. Use exponential backoff to handle rate limit errors gracefully. See [Error Handling Guide](/guides/production/error-handling#implement-retry-logic).
2. Pace your requests. Add client-side rate limiting to stay under limits.
3. Consider [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes), which don't have request-per-second limits and provide dedicated capacity for high-throughput workloads.
4. If you need higher limits, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) with details about your use case.

### All rate limits

#### Monthly usage limits

| Metric                                                                        | Starter plan   | Builder plan   | Standard plan  | Enterprise plan |
| :---------------------------------------------------------------------------- | :------------- | :------------- | :------------- | :-------------- |
| [Read units per month per org](#read-units-per-month-per-org)                 | 1,000,000      | 2,000,000      | Unlimited      | Unlimited       |
| [Write units per month per org](#write-units-per-month-per-org)               | 2,000,000      | 5,000,000      | Unlimited      | Unlimited       |
| [Embedding tokens per month per model](#embedding-tokens-per-month-per-model) | 5,000,000      | 10,000,000     | Unlimited      | Unlimited       |
| [Rerank requests per month per model](#rerank-requests-per-month-per-model)   | Model-specific | Model-specific | Model-specific | Model-specific  |

#### Data operation throughput limits

| Metric                                                                                                        | Starter plan | Builder plan | Standard plan | Enterprise plan |
| :------------------------------------------------------------------------------------------------------------ | :----------- | :----------- | :------------ | :-------------- |
| [Upsert size per second per namespace](#upsert-size-per-second-per-namespace)                                 | 50 MB        | 50 MB        | 50 MB         | 50 MB           |
| [Query read units per second per index](#query-read-units-per-second-per-index)                               | 2,000        | 2,000        | 2,000         | 2,000           |
| [Query requests per second per namespace](#query-requests-per-second-per-namespace)                           | 100          | 100          | 100           | 100             |
| [Update records per second per namespace](#update-records-per-second-per-namespace)                           | 100          | 100          | 100           | 100             |
| [Update requests per second per namespace](#update-requests-per-second-per-namespace)                         | 100          | 100          | 100           | 100             |
| [Update by metadata requests per second per namespace](#update-by-metadata-requests-per-second-per-namespace) | 5            | 5            | 5             | 5               |
| [Update by metadata requests per second per index](#update-by-metadata-requests-per-second-per-index)         | 500          | 500          | 500           | 500             |
| [Upsert requests per second per namespace](#upsert-requests-per-second-per-namespace)                         | 100          | 100          | 100           | 100             |
| [Fetch requests per second per index](#fetch-requests-per-second-per-index)                                   | 100          | 100          | 100           | 100             |
| [List requests per second per index](#list-requests-per-second-per-index)                                     | 200          | 200          | 200           | 200             |
| [Describe index stats requests per second per index](#describe-index-stats-requests-per-second-per-index)     | 100          | 100          | 100           | 100             |
| [Delete requests per second per namespace](#delete-requests-per-second-per-namespace)                         | 100          | 100          | 100           | 100             |
| [Delete records per second per namespace](#delete-records-per-second-per-namespace)                           | 5,000        | 5,000        | 5,000         | 5,000           |
| [Delete records per second per index](#delete-records-per-second-per-index)                                   | 5,000        | 5,000        | 5,000         | 5,000           |
| [Delete by metadata requests per second per namespace](#delete-by-metadata-requests-per-second-per-namespace) | 5            | 5            | 5             | 5               |
| [Delete by metadata requests per second per index](#delete-by-metadata-requests-per-second-per-index)         | 500          | 500          | 500           | 500             |

#### Model throughput limits

| Metric                                                                          | Starter plan   | Builder plan   | Standard plan  | Enterprise plan |
| :------------------------------------------------------------------------------ | :------------- | :------------- | :------------- | :-------------- |
| [Embedding tokens per minute per model](#embedding-tokens-per-minute-per-model) | Model-specific | Model-specific | Model-specific | Model-specific  |
| [Rerank requests per minute per model](#rerank-requests-per-minute-per-model)   | Model-specific | Model-specific | Model-specific | Model-specific  |

### Read units per month per org

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 1,000,000    | 2,000,000    | Unlimited     | Unlimited       |

[Read units](/guides/manage-cost/understanding-cost#read-units) measure the compute, I/O, and network resources used by [fetch](/guides/manage-data/fetch-data), [query](/guides/search/search-overview), and [list](/guides/manage-data/list-record-ids) requests to serverless indexes. When you reach the monthly read unit limit for an organization, fetch, query, and list requests to serverless indexes in the organization will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached your read unit limit for the current month limit. 
  To continue reading data, upgrade your plan. 
  ```
</Accordion>

To continue reading from serverless indexes in the organization, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan).

To check how close you are to the monthly read unit limit for your organization, do the following:

1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects).
2. Select the project.
3. Select any index in the project.
4. Look under **Usage**.

<Note>
  Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide.
</Note>

### Write units per month per org

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 2,000,000    | 5,000,000    | Unlimited     | Unlimited       |

[Write units](/guides/manage-cost/understanding-cost#write-units) measure the storage and compute resources used by [upsert](/guides/index-data/upsert-data), [update](/guides/manage-data/update-data), and [delete](/guides/manage-data/delete-data) requests to serverless indexes. When you reach the monthly write unit limit for an organization, upsert, update, and delete requests to serverless indexes in the organization will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached your write unit limit for the current month. 
  To continue writing data, upgrade your plan.
  ```
</Accordion>

To continue writing data to serverless indexes in the organization, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan).

To check how close you are to the monthly write unit limit for your organization, do the following:

1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects).
2. Select the project.
3. Select any index in the project.
4. Look under **Usage**.

### Upsert size per second per namespace

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 50 MB        | 50 MB        | 50 MB         | 50 MB           |

When you reach the per second [upsert](/guides/index-data/upsert-data) size for a namespace in an index, additional upserts will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max upsert size limit per second for index <index name>. 
  Pace your upserts or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Query read units per second per index

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 2,000        | 2,000        | 2,000         | 2,000           |

Pinecone measures [query](/guides/search/search-overview) usage in [read units](/guides/manage-cost/understanding-cost#read-units). When you reach the per second limit for queries across all namespaces in an index, additional queries will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max query read units per second for index <index name>. 
  Pace your queries or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

To check how many read units a query consumes, [check the query response](/guides/manage-cost/monitor-usage-and-costs#read-units).

<Note>
  Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide.
</Note>

### Query requests per second per namespace

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 100          | 100          | 100           | 100             |

When you reach the per second [query](/guides/search/search-overview) limit for a namespace in an index, additional queries will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the query QPS limit for namespace {namespace_name} ({limit} QPS). Pace your queries,
  consider Dedicated Read Nodes for your index, or contact Pinecone Support
  (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

<Note>
  Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide.
</Note>

### Update records per second per namespace

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 100          | 100          | 100           | 100             |

When you reach the per second [update](/guides/manage-data/update-data) limit for a namespace in an index, additional updates will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max update records per second for namespace <namespace name>. 
  Pace your update requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Update requests per second per namespace

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 100          | 100          | 100           | 100             |

When you reach the per second [update](/guides/manage-data/update-data) request limit for a namespace in an index, additional update requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the update QPS limit for namespace {namespace_name} ({limit} QPS). Pace your update requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

<Tip>
  If you need to update most of the records in a large namespace, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) for help creating an export to enable a faster and more cost-effective approach.
</Tip>

### Update by metadata requests per second per namespace

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 5            | 5            | 5             | 5               |

When you reach the per second [update by metadata](/guides/manage-data/update-data#update-metadata-across-multiple-records) request limit for a namespace in an index, additional update by metadata requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max update by metadata requests per second for namespace <namespace name>. Pace your update by metadata requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Update by metadata requests per second per index

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 500          | 500          | 500           | 500             |

When you reach the per second [update by metadata](/guides/manage-data/update-data#update-metadata-across-multiple-records) request limit across all namespaces in an index, additional update by metadata requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max update by metadata requests per second for index <index name>. Pace your update by metadata requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Upsert requests per second per namespace

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 100          | 100          | 100           | 100             |

When you reach the per second [upsert](/guides/index-data/upsert-data) request limit for a namespace in an index, additional upsert requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the upsert QPS limit for namespace {namespace_name} ({limit} QPS). Pace your upsert requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Fetch requests per second per index

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 100          | 100          | 100           | 100             |

When you reach the per second [fetch](/guides/manage-data/fetch-data) limit across all namespaces in an index, additional fetch requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max fetch requests per second for index <index name>.
  Pace your fetch requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

<Note>
  Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide.
</Note>

### List requests per second per index

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 200          | 200          | 200           | 200             |

When you reach the per second [list](/guides/manage-data/list-record-ids) limit across all namespaces in an index, additional list requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max list requests per second for index <index name>.
  Pace your list requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

<Note>
  Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide.
</Note>

### Describe index stats requests per second per index

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 100          | 100          | 100           | 100             |

When you reach the per second [describe index stats](/reference/api/2024-10/data-plane/describeindexstats) limit across all namespaces in an index, additional describe index stats requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max describe_index_stats requests per second for index <index>. 
  Pace your describe_index_stats requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Delete requests per second per namespace

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 100          | 100          | 100           | 100             |

When you reach the per second [delete](/guides/manage-data/delete-data) request limit for a namespace in an index, additional delete requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the delete QPS limit for namespace {namespace_name} ({limit} QPS). Pace your delete requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Delete records per second per namespace

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 5000         | 5000         | 5000          | 5000            |

When you reach the per second [delete](/guides/manage-data/delete-data) limit for a namespace in an index, additional deletes will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max delete records per second for namespace <namespace name>. 
  Pace your delete requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Delete records per second per index

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 5000         | 5000         | 5000          | 5000            |

When you reach the per second [delete](/guides/manage-data/delete-data) limit across all namespaces in an index, additional deletes will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max delete records per second for index <index name>. 
  Pace your delete requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Delete by metadata requests per second per namespace

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 5            | 5            | 5             | 5               |

When you reach the per second [delete by metadata](/guides/manage-data/delete-data#delete-records-by-metadata) request limit for a namespace in an index, additional delete by metadata requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max delete by metadata requests per second for namespace <namespace name>. Pace your delete by metadata requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Delete by metadata requests per second per index

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 500          | 500          | 500           | 500             |

When you reach the per second [delete by metadata](/guides/manage-data/delete-data#delete-records-by-metadata) request limit across all namespaces in an index, additional delete by metadata requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max delete by metadata requests per second for index <index name>. Pace your delete by metadata requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Embedding tokens per minute per model

| Embedding model              | Input type | Starter plan | Builder plan | Standard plan | Enterprise plan |
| :--------------------------- | :--------- | :----------- | :----------- | :------------ | :-------------- |
| `llama-text-embed-v2`        | Passage    | 250,000      | 250,000      | 1,000,000     | 1,000,000       |
|                              | Query      | 50,000       | 50,000       | 250,000       | 250,000         |
| `multilingual-e5-large`      | Passage    | 250,000      | 250,000      | 1,000,000     | 1,000,000       |
|                              | Query      | 50,000       | 50,000       | 250,000       | 250,000         |
| `pinecone-sparse-english-v0` | Passage    | 250,000      | 250,000      | 3,000,000     | 3,000,000       |
|                              | Query      | 250,000      | 250,000      | 3,000,000     | 3,000,000       |

When you reach the per minute token limit for an [embedding model](/guides/index-data/create-an-index#embedding-models) hosted by Pinecone, additional embeddings will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max embedding tokens per minute (<limit>) model '<model name>'' and input type '<passage|query>' for the current project. 
  To increase this limit, upgrade your plan.
  ```
</Accordion>

To increase this limit, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). Otherwise, you can handle this limit by [implementing retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic).

### Embedding tokens per month per model

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 5,000,000    | 10,000,000   | Unlimited     | Unlimited       |

When you reach the monthly token limit for an [embedding model](/guides/index-data/create-an-index#embedding-models) hosted by Pinecone, additional embeddings will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the embedding token limit (<limit>) for model <model name> for the current month. 
  To continue using this model, upgrade your plan.
  ```
</Accordion>

To increase this limit, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan) or [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Rerank requests per minute per model

| Reranking model        | Starter plan  | Builder plan  | Standard plan | Enterprise plan |
| :--------------------- | :------------ | :------------ | :------------ | :-------------- |
| `cohere-rerank-4-fast` | Not available | Not available | 300           | 300             |
| `cohere-rerank-3.5`    | Not available | Not available | 300           | 300             |
| `bge-reranker-v2-m3`   | 60            | 60            | 60            | 60              |
| `pinecone-rerank-v0`   | 60            | Not available | 60            | 60              |

When you reach the per minute request limit for a [reranking model](/guides/search/rerank-results#reranking-models) hosted by Pinecone, additional reranking requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max rerank requests per minute (<limit>) for model '<model name>' for the current project. 
  To increase this limit, upgrade your plan.
  ```
</Accordion>

To increase this limit, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan).

### Rerank requests per month per model

| Reranking model        | Starter plan  | Builder plan  | Standard plan | Enterprise plan |
| :--------------------- | :------------ | :------------ | :------------ | :-------------- |
| `cohere-rerank-4-fast` | Not available | Not available | Unlimited     | Unlimited       |
| `cohere-rerank-3.5`    | Not available | Not available | Unlimited     | Unlimited       |
| `bge-reranker-v2-m3`   | 500           | 1,000         | Unlimited     | Unlimited       |
| `pinecone-rerank-v0`   | 500           | Not available | Unlimited     | Unlimited       |

When you reach the monthly request limit for a [reranking model](/guides/search/rerank-results#reranking-models) hosted by Pinecone, additional reranking requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the rerank request limit (<limit>) for model <model name> for the current month. 
  To continue using this model, upgrade your plan.
  ```
</Accordion>

To increase this limit, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan) or [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Inference requests per second or minute, per project

| Metric                        | Starter plan | Builder plan | Standard plan | Enterprise plan |
| :---------------------------- | :----------- | :----------- | :------------ | :-------------- |
| Inference requests per second | 100          | 100          | 100           | 100             |
| Inference requests per minute | 2000         | 2000         | 2000          | 2000            |

When you reach the per second or per minute request limit, inference requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max inference requests per second (<limit>) for the current project.
  ```
</Accordion>

<Note>
  This error indicates per second or per minute, as applicable.
</Note>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic).

## Object limits

Object limits are restrictions on the number or size of objects in Pinecone. Object limits vary based on [pricing plan](https://www.pinecone.io/pricing/).

| Metric                                                                         | Starter plan | Builder plan | Standard plan | Enterprise plan |
| :----------------------------------------------------------------------------- | :----------- | :----------- | :------------ | :-------------- |
| [Projects per organization](#projects-per-organization)                        | 1            | 5            | 20            | 100             |
| [Users per organization](#users-per-organization)                              | 2            | 5            | Unlimited     | Unlimited       |
| [Serverless indexes per project](#serverless-indexes-per-project) <sup>1</sup> | 5            | 10           | 20            | 200             |
| [Serverless index storage per org](#serverless-index-storage-per-org)          | 2 GB         | 10 GB        | N/A           | N/A             |
| [Namespaces per serverless index](#namespaces-per-serverless-index)            | 100          | 1,000        | 100,000       | 100,000         |
| [Serverless backups per project](#serverless-backups-per-project)              | N/A          | N/A          | 500           | 1000            |
| [Collections per project](#collections-per-project)                            | 100          | N/A          | N/A           | N/A             |

<sup>1 On the Starter plan, all serverless indexes must be in the `us-east-1` region of AWS. Builder, Standard, and Enterprise plans can create indexes in any [supported region](/guides/index-data/create-an-index#cloud-regions).</sup><br />

### Projects per organization

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 1            | 5            | 20            | 100             |

When you reach this quota for an organization, trying to [create projects](/guides/projects/create-a-project) will fail and return a `403 - QUOTA_EXCEEDED` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max projects allowed in organization <org name>. 
  To add more projects, upgrade your plan.
  ```
</Accordion>

To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan) or [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Users per organization

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 2            | 5            | Unlimited     | Unlimited       |

When you reach this quota for an organization, trying to add users to the organization will fail. To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan).

### Serverless indexes per project

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 5            | 10           | 20            | 200             |

When you reach this quota for a project, trying to [create serverless indexes](/guides/index-data/create-an-index#create-a-serverless-index) in the project will fail and return a `403 - QUOTA_EXCEEDED` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max serverless indexes allowed in project <project>. 
  Use namespaces to partition your data into logical groups, or upgrade your plan to add more serverless indexes.
  ```
</Accordion>

To stay under this quota, consider using [namespaces](/guides/index-data/create-an-index#namespaces) instead of creating multiple indexes. Namespaces let you partition your data into logical groups within a single index. This approach not only helps you stay within index limits, but can also improve query performance and lower costs by limiting searches to relevant data subsets.

To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan).

### Serverless index storage per org

<Note>This limit applies to organizations on the Starter and Builder plans only.</Note>

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 2 GB         | 10 GB        | N/A           | N/A             |

When you've reached this quota for an organization, updates and upserts into serverless indexes will fail and return a `403 - QUOTA_EXCEEDED` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max storage allowed for organization <org name>. 
  To update or upsert new data, delete records or upgrade your plan.
  ```
</Accordion>

To continue writing data into your serverless indexes, [delete records](/guides/manage-data/delete-data) to bring your organization under the limit or [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan).

### Namespaces per serverless index

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 100          | 1,000        | 100,000       | 100,000         |

When you reach this quota for a serverless index, trying to [upsert records into a new namespace](/guides/index-data/upsert-data) in the index will fail and return a `403 - QUOTA_EXCEEDED` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max namespaces allowed in serverless index <index name>. 
  To add more namespaces, upgrade your plan.
  ```
</Accordion>

To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan).

<Note>
  [Namespaces per serverless index](/reference/api/database-limits#namespaces-per-serverless-index) vary by plan. On the Standard and Enterprise plans, Pinecone can accommodate million-scale namespaces and beyond for specific use cases. If your application requires more than 100,000 namespaces, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).
</Note>

### Serverless backups per project

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| N/A          | N/A          | 500           | 1000            |

Backups are not available on the Starter or Builder plans. On the Standard and Enterprise plans, when you reach this quota for a project, trying to [create serverless backups](/guides/manage-data/back-up-an-index) in the project will fail and return a `403 - QUOTA_EXCEEDED` status with the following error:

<Accordion title="Error response">
  ```
  Backup failed to create. Quota for number of backups per index exceeded.
  ```
</Accordion>

### Collections per project

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 100          | N/A          | N/A           | N/A             |

When you reach this quota for a project, trying to [create collections](/guides/manage-data/back-up-an-index) in the project will fail and return a `403 - QUOTA_EXCEEDED` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max collections allowed in project <project name>. 
  To add more collections, upgrade your plan.
  ```
</Accordion>

To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan).

## Operation limits

Operation limits are restrictions on the size, number, or other characteristics of operations in Pinecone. Operation limits are fixed and do not vary based on pricing plan.

### Upsert limits

| Metric                                                             | Limit                                                         |
| :----------------------------------------------------------------- | :------------------------------------------------------------ |
| Max [batch size](/guides/index-data/upsert-data#upsert-in-batches) | 2 MB or 1000 records with vectors <br /> 96 records with text |
| Max documents per upsert request                                   | 1000                                                          |
| Max document upsert request size                                   | 2 MB                                                          |
| Max document size                                                  | 2 MB                                                          |
| Max `full_text_search` string fields per schema                    | 100                                                           |
| Max size per `full_text_search` string field                       | 100 KB                                                        |
| Max tokens per `full_text_search` string field                     | 10,000                                                        |
| Max bytes per token                                                | 256 bytes                                                     |
| Max filterable metadata size per document                          | 40 KB                                                         |
| Max length for a record ID                                         | 512 characters                                                |
| Max dimensionality for dense vectors                               | 20,000                                                        |
| Max non-zero values for sparse vectors                             | 2048                                                          |
| Max dimensionality for sparse vectors                              | 4.2 billion                                                   |

The 40 KB filterable metadata limit does not apply to `full_text_search` text fields.

### Import limits

<Note>
  If your import exceeds these limits, you'll get an error specifying the limit exceeded. See [Troubleshooting](/guides/index-data/import-data#troubleshooting) for details.
</Note>

| Metric                                        | Limit     |
| :-------------------------------------------- | :-------- |
| Max namespaces per import                     | 10,000    |
| Max total input data size (on-demand indexes) | 1 TB      |
| Max total input data size (DRN indexes)       | Unlimited |
| Max files per import                          | 100,000   |
| Max size per file                             | 10 GB     |

The total input data size limit does not apply to indexes with [dedicated read nodes](/guides/index-data/dedicated-read-nodes).

Bulk import supports indexes without a schema definition (Parquet files) and indexes with document schemas ([JSONL files](/guides/search/full-text-search#bulk-import)). Semantic-text (auto-embedded) fields are not yet supported in document schemas.

### Query limits

| Metric            | Limit  |
| :---------------- | :----- |
| Max `top_k` value | 10,000 |
| Max result size   | 4MB    |

The query result size is affected by the dimension of the dense vectors and whether or not dense vector values and metadata are included in the result.

<Tip>
  If a query fails due to exceeding the 4MB result size limit, choose a lower `top_k` value, or use `include_metadata=False` or `include_values=False` to exclude metadata or values from the result. For better performance, especially with higher `top_k` values, avoid including vector values unless you need them.
</Tip>

### Fetch limits

**Fetch by ID limits:**

| Metric                           | Limit |
| :------------------------------- | :---- |
| Max record IDs per fetch request | 1,000 |

**Fetch by metadata limits:**

| Metric                   | Limit                               |
| :----------------------- | :---------------------------------- |
| Max records per response | 10,000                              |
| Max response size        | 4 MB                                |
| Max request rate         | 5 requests per second per namespace |

To retrieve more than 10,000 matching records, paginate through results using the `paginationToken` parameter. See [Fetch records by metadata](/guides/manage-data/fetch-data#fetch-records-by-metadata).

### Delete limits

| Metric                            | Limit |
| :-------------------------------- | :---- |
| Max record IDs per delete request | 1,000 |

### Metadata filter limits

The following limits apply to [metadata filter expressions](/guides/search/filter-by-metadata#metadata-filter-expressions) used in query, delete, update, and fetch operations.

| Limit                                       | Value  | Description                                                                                                                                                                                                      |
| :------------------------------------------ | :----- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Maximum values per `$in` or `$nin` operator | 10,000 | Each `$in` or `$nin` operator accepts up to 10,000 values in its array. This limit applies per operator—if you have multiple `$in` operators in a single filter, each is independently limited to 10,000 values. |

When you exceed this limit, the request will fail and return a `400 - BAD_REQUEST` error.

#### Rationale

Large `$in` operators can impact query performance and cost. Filters with thousands of values increase request payload size and end-to-end latency. Additionally, using large filters typically indicates a shared namespace architecture, which increases query costs—queries scan the entire namespace regardless of filters.

#### Alternative approaches

If you need to filter by more than 10,000 values, consider these alternatives:

* **Use namespaces for tenant isolation**: Instead of filtering by tenant IDs within a single namespace, create separate namespaces for each tenant or tenant group. This can also reduce query costs. See [Design for multi-tenancy](/guides/index-data/data-modeling#design-for-multi-tenancy).
* **Use broader access control groups**: Instead of filtering by individual user IDs, filter by organization, project, or role. This reduces the number of values in your `$in` filter. See [Design for multi-tenancy](/guides/index-data/data-modeling#use-access-control-groups-instead-of-individual-ids).
* **Post-filter client-side**: Retrieve a larger top K without filtering (for example, top 1000), then filter results client-side.
* **Run multiple queries**: Split your filter into multiple queries with smaller `$in` operators and combine the results client-side.

<Tip>
  To avoid hitting this limit in production, validate the size of your `$in` and `$nin` arrays in your application code before making the request to Pinecone.
</Tip>

## Identifier limits

An identifier is a string of characters used to identify "named" [objects in Pinecone](/guides/get-started/concepts). The following Pinecone objects use strings as identifiers:

| Object                                                    | Field       | Max # characters | Allowed characters                                                                                                                        |
| --------------------------------------------------------- | ----------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| [Organization](/guides/get-started/concepts#organization) | `name`      | 512              | <ul><li>UTF-8 except `\0`</li><li>Cannot be empty</li></ul>                                                                               |
| [Project](/guides/get-started/concepts#project)           | `name`      | 512              | <ul><li>UTF-8 except `\0`</li><li>Cannot be empty</li></ul>                                                                               |
| [Index](/guides/get-started/concepts#index)               | `name`      | 45               | <ul><li>`a-z`, `0-9`, and `-`</li><li>Must be lowercase</li><li>Cannot start or end with `-`</li><li>Cannot be empty</li></ul>            |
| [Namespace](/guides/get-started/concepts#namespace)       | `namespace` | 512              | <ul><li>ASCII except `\0`</li><li>For the default namespace, use `""` (or `"__default__"`, in API versions `2025-04` and later)</li></ul> |
| [Record](/guides/get-started/concepts#record)             | `id`        | 512              | <ul><li>ASCII except `\0`</li><li>Cannot be empty</li></ul>                                                                               |


# Errors
Source: https://docs.pinecone.io/reference/api/errors

Pinecone REST API: Pinecone uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the range.

Pinecone uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the `2xx` range indicate success, codes in the `4xx` range indicate an error that failed given the information provided, and codes in the `5xx` range indicate an error with Pinecone's servers.

For guidance on handling errors in production, see [Error handling](/guides/production/error-handling).

## 200 - OK

The request succeeded.

## 201 - CREATED

The request succeeded and a new resource was created.

## 202 - NO CONTENT

The request succeeded, but there is no content to return.

## 400 - INVALID ARGUMENT

The request failed due to an invalid argument.

## 401 - UNAUTHENTICATED

The request failed due to a missing or invalid [API key](/guides/projects/understanding-projects#api-keys).

## 402 - PAYMENT REQUIRED

The request failed due to delinquent payment or account deactivation for non-payment. See [Account deactivation for non-payment](/guides/organizations/manage-billing/non-payment-account-deactivation).

## 403 - FORBIDDEN

The request failed due to an exceeded [quota](/reference/api/database-limits#object-limits) or [index deletion protection](/guides/manage-data/manage-indexes#configure-deletion-protection).

## 404 - NOT FOUND

The request failed because the resource was not found.

## 409 - ALREADY EXISTS

The request failed because the resource already exists.

## 412 - FAILED PRECONDITIONS

The request failed due to preconditions not being met. |

## 422 - UNPROCESSABLE ENTITY

The request failed because the server was unable to process the contained instructions.

## 429 - TOO MANY REQUESTS

The request was [rate-limited](/reference/api/database-limits#rate-limits). [Implement retry logic with exponential backoff](/guides/production/error-handling#handle-rate-limits-429) to handle this error.

## 500 - UNKNOWN

An internal server error occurred. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) to handle transient errors.

## 502 - BAD GATEWAY

The API gateway received an invalid response from a backend service. This is typically a temporary error. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) to handle transient errors.

## 503 - UNAVAILABLE

The server is currently unavailable. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) to handle transient errors.

## 504 - GATEWAY TIMEOUT

The API gateway did not receive a timely response from the backend server. This can occur due to slow requests or backend processing delays. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) to handle transient errors.


# API reference
Source: https://docs.pinecone.io/reference/api/introduction

Pinecone API reference overview for Database, Inference, and Admin endpoints with supported SDKs including Python, Node.js, Java, and Go.

Pinecone's APIs let you interact programmatically with your Pinecone account.

<Note>
  [SDK versions](/reference/pinecone-sdks#sdk-versions) are pinned to specific API versions.
</Note>

## Database

Use the Database API to store and query records in [Pinecone Database](/guides/get-started/quickstart).

The following Pinecone SDKs support the Database API:

<CardGroup>
  <Card title="CLI" icon="terminal" href="/reference/cli/overview" />

  <Card title="Python SDK" icon="python" href="/reference/sdks/python/overview" />

  <Card title="Node.js SDK" icon="node-js" href="/reference/sdks/node/overview" />

  <Card title="Java SDK" icon="java" href="/reference/sdks/java/overview" />

  <Card title="Go SDK" icon="golang" href="/reference/sdks/go/overview" />
</CardGroup>

## Inference

Use the Inference API to generate vector embeddings and rerank results using [embedding models](/guides/index-data/create-an-index#embedding-models) and [reranking models](/guides/search/rerank-results#reranking-models) hosted on Pinecone's infrastructure.

There are two ways to use the Inference API:

* As a standalone service, through the [Rerank documents](/reference/api/latest/inference/rerank) and [Generate vectors](/reference/api/latest/inference/generate-embeddings) endpoints.
* As an integrated part of database operations, through the [Create an index with integrated embedding](/reference/api/latest/control-plane/create_for_model), [Upsert text](/reference/api/latest/data-plane/upsert_records), and [Search with text](/reference/api/latest/data-plane/search_records) endpoints.

The following Pinecone SDKs support using the Inference API:

<CardGroup>
  <Card title="Python SDK" icon="python" href="/reference/sdks/python/overview" />

  <Card title="Node.js SDK" icon="node-js" href="/reference/sdks/node/overview" />

  <Card title="Java SDK" icon="java" href="/reference/sdks/java/overview" />

  <Card title="Go SDK" icon="golang" href="/reference/sdks/go/overview" />
</CardGroup>


# Known limitations
Source: https://docs.pinecone.io/reference/api/known-limitations

Known limitations and feature restrictions for Pinecone indexes, including upsert consistency, metadata rules, and serverless caveats.

This page describes known limitations and feature restrictions in Pinecone.

## General

* [Upserts](/guides/index-data/upsert-data)
  * Pinecone is eventually consistent, so there can be a slight delay before upserted records are available to query.

    After upserting records, use the [`describe_index_stats`](/reference/api/2024-10/data-plane/describeindexstats) operation to check if the current vector count matches the number of records you expect, although this method may not work for pod-based indexes with multiple replicas.
  * Only indexes using the [dotproduct distance metric](/guides/index-data/indexing-overview#dotproduct) support querying sparse-dense vectors.

    Upserting, updating, and fetching sparse-dense vectors in indexes with a different distance metric will succeed, but querying will return an error.
  * Indexes created before February 22, 2023 do not support sparse vectors.
* [Metadata](/guides/index-data/upsert-data#upsert-with-metadata-filters)
  * Null metadata values aren't supported. Instead of setting a key to `null`, remove the key from the metadata payload.
  * Nested JSON objects are not supported.

## Serverless indexes

Serverless indexes do not support the following features:

* [Filtering index statistics by metadata](/reference/api/2024-10/data-plane/describeindexstats)
* [Private endpoints](/guides/production/configure-private-endpoints)

  * This feature is available on AWS only.


# API versioning
Source: https://docs.pinecone.io/reference/api/versioning

Pinecone REST API: Pinecone's APIs are versioned to ensure that your applications continue to work as expected as the platform evolves.

Pinecone's APIs are versioned to ensure that your applications continue to work as expected as the platform evolves. Versions are named by release date in the format `YYYY-MM`, for example, `2025-10`.

## Release schedule

On a quarterly basis, Pinecone releases a new **stable** API version as well as a **release candidate** of the next stable version.

* **Stable:** Each stable version remains unchanged and supported for a minimum of 12 months. Since stable versions are released every 3 months, this means you have at least 9 months to test and migrate your app to the newest stable version before support for the previous version is removed.

* **Release candidate:** The release candidate gives you insight into the upcoming changes in the next stable version. It is available for approximately 3 months before the release of the stable version and can include new features, improvements, and [breaking changes](#breaking-changes).

Below is an example of Pinecone's release schedule:

<img />

<img />

## Specify an API version

<Warning>
  When using the API directly, it is important to specify an API version in your requests. If you don't, requests default to the oldest supported stable version. Once support for that version ends, your requests will default to the next oldest stable version, which could include breaking changes that require you to update your integration.
</Warning>

To specify an API version, set the `X-Pinecone-Api-Version` header to the version name.

For example, to use the latest stable version (`2026-04`) to describe an index, set the `X-Pinecone-Api-Version` header:

```shell curl theme={null}
PINECONE_API_KEY="YOUR_API_KEY"

curl -i -X GET "https://api.pinecone.io/indexes/movie-recommendations" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2026-04"
```

To use an older version, specify that version instead.

## SDK versions

Official [Pinecone SDKs](/reference/pinecone-sdks) provide convenient access to Pinecone APIs. SDK versions are pinned to specific API versions. When a new API version is released, a new version of the SDK is also released.

For the mapping between SDK and API versions, see [SDK versions](/reference/pinecone-sdks#sdk-versions).

## Breaking changes

Breaking changes are changes that can potentially break your integration with a Pinecone API. Breaking changes include:

* Removing an entire operation
* Removing or renaming a parameter
* Removing or renaming a response field
* Adding a new required parameter
* Making a previously optional parameter required
* Changing the type of a parameter or response field
* Removing enum values
* Adding a new validation rule to an existing parameter
* Changing authentication or authorization requirements

## Non-breaking changes

Non-breaking changes are additive and should not break your integration. Additive changes include:

* Adding an operation
* Adding an optional parameter
* Adding an optional request header
* Adding a response field
* Adding a response header
* Adding enum values

## Get updates

To ensure you always know about upcoming API changes, follow the [Release notes](/release-notes/).


# CLI authentication
Source: https://docs.pinecone.io/reference/cli/authentication

Authenticate the Pinecone CLI using user login, service accounts, or API keys, including auth priority and Admin API access rules.

This document describes how to authenticate the Pinecone CLI to manage your Pinecone resources.

## Authentication methods

| Method                              | Admin API | Control/data plane | Best for                         |
| ----------------------------------- | --------- | ------------------ | -------------------------------- |
| [User login](#user-login)           | ✅         | ✅                  | Interactive use                  |
| [Service account](#service-account) | ✅         | ✅                  | Automation with Admin API access |
| [API key](#api-key)                 | ❌         | ✅                  | Simple automation, CI/CD         |

### User login

Authenticate through a web browser. The token refreshes automatically and stays valid for up to 120 days (re-auth required after 30 days of inactivity).

```bash theme={null}
pc auth login
```

The CLI auto-targets your default organization and its first project. Change with `pc target -o "my-org" -p "my-project"`.

### Service account

Authenticate with credentials from a [service account](/guides/organizations/manage-service-accounts).

```bash theme={null}
pc auth configure --client-id "ID" --client-secret "SECRET"

# Or via environment variables
export PINECONE_CLIENT_ID="your-client-id"
export PINECONE_CLIENT_SECRET="your-client-secret"
```

The CLI auto-targets the service account's organization. For projects: auto-selects if one exists, prompts if multiple exist, or set manually with `pc target -p "my-project"`.

### API key

Authenticate with an [API key](/guides/projects/manage-api-keys). API keys can't access the Admin API.

```bash theme={null}
pc auth configure --api-key "YOUR_API_KEY"

# Or via environment variable
export PINECONE_API_KEY="your-api-key"
```

<Warning>
  API keys are scoped to a specific project. When set, control/data plane operations use the **key's project**, ignoring any [target context](/reference/cli/target-context) you've set.
</Warning>

## Auth priority

When multiple credentials exist, the CLI chooses based on operation type. Within each credential type, environment variables take precedence over stored configuration.

**Control/data plane operations:**

1. API key
2. User login token (via [managed keys](#managed-keys))
3. Service account (via [managed keys](#managed-keys))

**Admin API operations:**

1. User login token
2. Service account

<Note>
  User login and service account are mutually exclusive when configured via CLI commands—each clears the other. However, service account env vars don't clear a stored user login token.
</Note>

**Example scenarios:**

* If `PINECONE_API_KEY` is set, the CLI uses it for control/data plane operations, regardless of any stored API key.
* If you're logged in via `pc auth login` and also have `PINECONE_CLIENT_ID`/`PINECONE_CLIENT_SECRET` set, the user login token is used for everything—the service account env vars are ignored.
* If you have an API key configured and are also logged in, the API key is used for control/data plane operations, but user login is used for Admin API operations (since API keys can't access Admin API).

## Managed keys

When using user login or service account (without a default API key), the CLI automatically creates and manages API keys for control/data plane operations. This happens transparently on first use.

* **Stored locally:** `~/.config/pinecone/secrets.yaml` (permissions 0600)
* **Stored remotely:** Visible in console as `pinecone-cli-{id}` with origin `cli_created`

```bash theme={null}
# List locally tracked managed keys
pc auth local-keys list

# Delete managed keys (local + remote)
pc auth local-keys prune

# Delete only CLI-created managed keys
pc auth local-keys prune --origin cli

# Delete only user-created managed keys
pc auth local-keys prune --origin user

# Delete a specific API key by ID
pc api-key delete --id "KEY_ID"
```

<Note>
  When you run `pc api-key create --store` for a project that already has a CLI-created managed key, the CLI automatically deletes the old remote key before storing the new one.
</Note>

## Logging out

```bash theme={null}
pc auth logout
```

Clears all local auth data: tokens, credentials, API keys, managed keys, and [target context](/reference/cli/target-context).

<Note>
  `pc auth logout` doesn't delete managed keys from Pinecone's servers. Run `pc auth local-keys prune` first for full cleanup.
</Note>

## Local storage

Auth data is stored in `~/.config/pinecone/` with 0600 permissions:

| File           | Contents                                                         |
| -------------- | ---------------------------------------------------------------- |
| `secrets.yaml` | OAuth token, service account credentials, API keys, managed keys |
| `state.yaml`   | Target org/project                                               |
| `config.yaml`  | CLI settings (color, environment)                                |

## Check status

```bash theme={null}
pc auth status
```

Shows your current authentication method, target organization and project, token expiration (for user login), and environment configuration.


# CLI command reference
Source: https://docs.pinecone.io/reference/cli/command-reference

Complete Pinecone CLI command reference covering syntax, subcommands, flags, help output, and exit codes for auth, index, and project.

This document provides a complete reference for all Pinecone CLI commands.

## Command structure

The Pinecone CLI uses a hierarchical command structure. Each command consists of a primary command followed by one or more subcommands and optional flags.

```bash theme={null}
pc <command> <subcommand> [flags]
pc <command> <subcommand> <subcommand> [flags]
```

For example:

```bash theme={null}
# Top-level command with flags
pc target -o "organization-name" -p "project-name"

# Command (index) and subcommand (list)
pc index list

# Command (index) and subcommand (create) with flags
pc index create \
  --name my-index \
  --dimension 1536 \
  --metric cosine \
  --cloud aws \
  --region us-east-1

# Command (auth) and nested subcommands (local-keys prune) with flags
pc auth local-keys prune --id proj-abc123 --skip-confirmation
```

## Getting help

The CLI provides help for commands at every level:

```bash theme={null}
# top-level help
pc --help
pc -h

# command help
pc auth --help
pc index --help
pc project --help

# subcommmand help
pc index create --help
pc project create --help
pc auth configure --help

# nested subcommand help
pc auth local-keys prune --help
```

## Exit codes

All commands return exit code `0` for success and `1` for error.

## Available commands

This section describes all commands offered by the Pinecone CLI.

### Top-level commands

<AccordionGroup>
  <Accordion title="pc login (Authenticate via user login)">
    **Description**

    Authenticate via a web browser. After login, set a [target org and project](/reference/cli/target-context) with `pc target` before accessing data. This command defaults to an initial organization and project to which
    you have access (these values display in the terminal), but you can change them with `pc target`.

    **Usage**

    ```bash theme={null}
    pc login
    ```

    **Flags**

    None

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Log in via browser
    pc login

    # Then set target context
    pc target -o "my-org" -p "my-project"
    ```

    <Note>
      This is an alias for `pc auth login`. Both commands perform the same operation.
    </Note>
  </Accordion>

  <Accordion title="pc logout (Clear credentials / log out)">
    **Description**

    Clears all authentication data from local storage, including:

    * User login token
    * Service account credentials (client ID and secret)
    * Default (manually specified) API key
    * Locally managed keys (for all projects)
    * Target organization and project context

    **Usage**

    ```bash theme={null}
    pc logout
    ```

    **Flags**

    None

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Clear all credentials and context
    pc logout
    ```

    <Note>
      This is an alias for `pc auth logout`. Both commands perform the same operation. Does not delete managed API keys from Pinecone's servers. Run `pc auth local-keys prune` before logging out to fully clean up.
    </Note>
  </Accordion>

  <Accordion title="pc target (Set target organization and project)">
    **Description**

    Set the target organization and project for the CLI. Supports interactive organization and project selection or direct specification via flags.  For details, see [CLI target context](/reference/cli/target-context).

    **Usage**

    ```bash theme={null}
    pc target [flags]
    ```

    **Flags**

    | Long flag           | Short flag | Description                    |
    | :------------------ | :--------- | :----------------------------- |
    | `--clear`           |            | Clear target context           |
    | `--json`            | `-j`       | Output in JSON format          |
    | `--org`             | `-o`       | Organization name              |
    | `--organization-id` |            | Organization ID                |
    | `--project`         | `-p`       | Project name                   |
    | `--project-id`      |            | Project ID                     |
    | `--show`            | `-s`       | Display current target context |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Interactive targeting after login
    pc login
    pc target

    # Set specific organization and project
    pc target -o "my-org" -p "my-project"

    # Show current context
    pc target --show

    # Clear all context
    pc target --clear
    ```
  </Accordion>

  <Accordion title="pc version (Show CLI version)">
    **Description**

    Displays version information for the CLI, including the version number, commit SHA, and build date.

    **Usage**

    ```bash theme={null}
    pc version
    ```

    **Flags**

    None

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Display version information
    pc version
    ```
  </Accordion>

  <Accordion title="pc whoami (Show current user)">
    **Description**

    Displays information about the currently authenticated user. To use this command, you must be authenticated via user login.

    **Usage**

    ```bash theme={null}
    pc whoami
    ```

    **Flags**

    None

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    pc whoami
    ```

    <Note>
      This is an alias for `pc auth whoami`. Both commands perform the same operation.
    </Note>
  </Accordion>
</AccordionGroup>

### Authentication

<AccordionGroup>
  <Accordion title="pc auth clear (Clear specific credentials)">
    **Description**

    Selectively clears specific authentication data without affecting other credentials. At least one flag is required.

    **Usage**

    ```bash theme={null}
    pc auth clear [flags]
    ```

    **Flags**

    | Long flag           | Short flag | Description                                         |
    | :------------------ | :--------- | :-------------------------------------------------- |
    | `--api-key`         |            | Clear only the default (manually specified) API key |
    | `--service-account` |            | Clear only service account credentials              |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Clear only the default (manually specified) API key
    pc auth clear --api-key
    pc auth status

    # Clear service account
    pc auth clear --service-account
    ```

    <Note>
      More surgical than `pc auth logout`. Does not clear user login token or managed keys. For those, use `pc auth logout` or `pc auth local-keys prune`.
    </Note>
  </Accordion>

  <Accordion title="pc auth configure (Configure service account or API key)">
    **Description**

    Configures service account credentials or a default (manually specified) API key.

    Service accounts automatically target the organization and prompt for project selection, unless there is only one project. A default API key overrides any previously specified target organization/project context. When setting a service account, this operation clears the user login token, if one exists.
    For details, see [CLI target context](/reference/cli/target-context).

    **Usage**

    ```bash theme={null}
    pc auth configure [flags]
    ```

    **Flags**

    | Long flag               | Short flag | Description                                          |
    | :---------------------- | :--------- | :--------------------------------------------------- |
    | `--api-key`             |            | Default API key to use for authentication            |
    | `--client-id`           |            | Service account client ID                            |
    | `--client-secret`       |            | Service account client secret                        |
    | `--client-secret-stdin` |            | Read client secret from stdin                        |
    | `--json`                | `-j`       | Output in JSON format                                |
    | `--project-id`          | `-p`       | Target project ID (optional, interactive if omitted) |
    | `--prompt-if-missing`   |            | Prompt for missing credentials                       |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Service account setup (auto-targets org and prompts for project)
    pc auth configure --client-id my-id --client-secret my-secret

    # Service account with specific project
    pc auth configure \
      --client-id my-id \
      --client-secret my-secret \
      -p proj-123

    # Default API key (overrides any target context)
    pc auth configure --api-key pcsk_abc123
    ```

    <Note>
      `pc auth configure --api-key "YOUR_API_KEY"` does the same thing as `pc config set-api-key "YOUR_API_KEY"`. To learn about targeting a project after authenticating with a service account, see [CLI target context](/reference/cli/target-context).
    </Note>
  </Accordion>

  <Accordion title="pc auth local-keys list (List managed keys)">
    **Description**

    Displays all [managed API keys](/reference/cli/authentication#managed-keys) stored locally by the CLI, with various details.

    **Usage**

    ```bash theme={null}
    pc auth local-keys list [flags]
    ```

    **Flags**

    | Long flag  | Short flag | Description                                |
    | :--------- | :--------- | :----------------------------------------- |
    | `--json`   | `-j`       | Output in JSON format                      |
    | `--reveal` |            | Show the actual API key values (sensitive) |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # List all locally managed keys
    pc auth local-keys list

    # Show key values
    pc auth local-keys list --reveal

    # After storing a key
    pc api-key create -n "my-key" --store
    pc auth local-keys list
    ```
  </Accordion>

  <Accordion title="pc auth local-keys prune (Delete managed keys)">
    **Description**

    Deletes locally stored [managed API keys](/reference/cli/authentication#managed-keys) from local storage and Pinecone's servers. Filters by origin (`cli`/`user`/`all`) or project ID.

    **Usage**

    ```bash theme={null}
    pc auth local-keys prune [flags]
    ```

    **Flags**

    | Long flag             | Short flag | Description                                                 |
    | :-------------------- | :--------- | :---------------------------------------------------------- |
    | `--dry-run`           |            | Preview deletions without applying                          |
    | `--id`                |            | Prune keys for specific project ID only                     |
    | `--json`              | `-j`       | Output in JSON format                                       |
    | `--origin`            | `-o`       | Filter by origin - `cli`, `user`, or `all` (default: `all`) |
    | `--skip-confirmation` |            | Skip confirmation prompt                                    |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Preview deletions
    pc auth local-keys prune --dry-run

    # Delete CLI-created keys only
    pc auth local-keys prune -o cli --skip-confirmation

    # Delete for specific project
    pc auth local-keys prune --id proj-abc123

    # Before/after check
    pc auth local-keys list
    pc auth local-keys prune -o cli
    pc auth local-keys list
    ```

    <Note>
      This deletes keys from both local storage and Pinecone servers. Use `--dry-run` to preview before committing.
    </Note>
  </Accordion>

  <Accordion title="pc auth login (Authenticate via user login)">
    **Description**

    Authenticate via user login in the web browser. After login, [set a target org and project](/reference/cli/target-context).

    **Usage**

    ```bash theme={null}
    pc auth login
    pc login  # shorthand
    ```

    **Flags**

    None

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Login and set target
    pc auth login
    pc target -o "my-org" -p "my-project"
    pc index list
    ```

    <Note>
      Tokens refresh automatically and remain valid for up to 120 days. If you're inactive for more than 30 days, you must re-authenticate. Logging in clears any existing service account credentials. This command does the same thing as `pc login`.
    </Note>
  </Accordion>

  <Accordion title="pc auth logout (Clear authentication credentials)">
    **Description**

    Clears all authentication data from local storage, including:

    * User login token
    * Service account credentials (client ID and secret)
    * Default (manually specified) API key
    * Locally managed keys (for all projects)
    * Target organization and project context

    **Usage**

    ```bash theme={null}
    pc auth logout
    ```

    **Flags**

    None

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Clear all credentials and context
    pc auth logout
    ```

    <Note>
      This command does the same thing as `pc logout`. Does not delete managed API keys from Pinecone's servers. Run `pc auth local-keys prune` before logging out to fully clean up.
    </Note>
  </Accordion>

  <Accordion title="pc auth status (Show authentication status)">
    **Description**

    Shows details about all configured authentication methods.

    **Usage**

    ```bash theme={null}
    pc auth status [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description           |
    | :-------- | :--------- | :-------------------- |
    | `--json`  | `-j`       | Output in JSON format |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Check status after login
    pc auth login
    pc auth status

    # JSON output for scripting
    pc auth status --json
    ```
  </Accordion>

  <Accordion title="pc auth whoami (Show current user information)">
    **Description**

    Displays information about the currently authenticated user. To use this command, you must be authenticated via user login.

    **Usage**

    ```bash theme={null}
    pc auth whoami
    ```

    **Flags**

    None

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    pc auth whoami
    ```

    <Note>
      This command does the same thing as `pc whoami`.
    </Note>
  </Accordion>
</AccordionGroup>

### Indexes

<AccordionGroup>
  <Accordion title="pc index configure (Update index configuration)">
    **Description**

    Modifies the configuration of an existing index.

    **Usage**

    ```bash theme={null}
    pc index configure [flags]
    ```

    **Flags**

    | Long flag                | Short flag | Description                                                     |
    | :----------------------- | :--------- | :-------------------------------------------------------------- |
    | `--index-name`           | `-i`       | Name of index to configure (required)                           |
    | `--deletion-protection`  |            | Enable or disable deletion protection - `enabled` or `disabled` |
    | `--tags`                 |            | Custom user tags (key=value pairs)                              |
    | `--json`                 | `-j`       | Output in JSON format                                           |
    | **Dedicated read nodes** |            |                                                                 |
    | `--read-mode`            |            | Read capacity mode - `ondemand` or `dedicated`                  |
    | `--read-node-type`       |            | Node type for dedicated read - `b1` or `t1`                     |
    | `--read-shards`          |            | Number of shards for dedicated read capacity                    |
    | `--read-replicas`        |            | Number of replicas for dedicated read capacity                  |
    | **Integrated embedding** |            |                                                                 |
    | `--model`                |            | Embedding model name                                            |
    | `--field-map`            |            | Field mapping for embedding (key=value pairs)                   |
    | `--read-parameters`      |            | Read parameters for embedding model (key=value pairs)           |
    | `--write-parameters`     |            | Write parameters for embedding model (key=value pairs)          |
    | **Pods**                 |            |                                                                 |
    | `--pod-type`             | `-t`       | Type of pod to use; can only upgrade when configuring           |
    | `--replicas`             | `-r`       | Number of replicas of the index to configure                    |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Enable deletion protection
    pc index configure --index-name my-index --deletion-protection enabled

    # Add tags
    pc index configure --index-name my-index --tags environment=production,team=ml

    # Switch to dedicated read capacity
    pc index configure --index-name my-index \
      --read-mode dedicated \
      --read-node-type b1 \
      --read-shards 2 \
      --read-replicas 2

    # Verify changes
    pc index describe --index-name my-index
    ```

    <Note>
      Configuration changes may take some time to take effect.
    </Note>
  </Accordion>

  <Accordion title="pc index create (Create a new index)">
    **Description**

    Creates a new index in your Pinecone project. Supports serverless, pod-based, integrated (with embedding model), and BYOC (Bring Your Own Cloud) index types.

    **Usage**

    ```bash theme={null}
    pc index create [flags]
    ```

    **Flags**

    | Long flag                | Short flag | Description                                                                    |
    | :----------------------- | :--------- | :----------------------------------------------------------------------------- |
    | `--name`                 | `-n`       | Index name (required)                                                          |
    | `--dimension`            | `-d`       | Vector dimension (required for standard indexes, optional for integrated)      |
    | `--metric`               | `-m`       | Similarity metric - `cosine`, `euclidean`, or `dotproduct` (default: `cosine`) |
    | `--cloud`                | `-c`       | Cloud provider - `aws`, `gcp`, or `azure`                                      |
    | `--region`               | `-r`       | Cloud region                                                                   |
    | `--vector-type`          | `-v`       | Vector type - `dense` or `sparse` (serverless only)                            |
    | `--source-collection`    |            | Name of the source collection from which to create the index                   |
    | `--schema`               |            | Metadata schema to control which fields are indexed (comma-separated)          |
    | `--deletion-protection`  |            | Deletion protection - `enabled` or `disabled`                                  |
    | `--tags`                 |            | Custom user tags (key=value pairs)                                             |
    | `--json`                 | `-j`       | Output in JSON format                                                          |
    | **Integrated indexes**   |            |                                                                                |
    | `--model`                |            | Integrated embedding model name                                                |
    | `--field-map`            |            | Field mapping for integrated embedding (key=value pairs)                       |
    | `--read-parameters`      |            | Read parameters for embedding model (key=value pairs)                          |
    | `--write-parameters`     |            | Write parameters for embedding model (key=value pairs)                         |
    | **BYOC indexes**         |            |                                                                                |
    | `--byoc-environment`     |            | BYOC environment to use for the index                                          |
    | **Dedicated read nodes** |            |                                                                                |
    | `--read-mode`            |            | Read capacity mode - `ondemand` or `dedicated` (default: `ondemand`)           |
    | `--read-node-type`       |            | Node type for dedicated read - `b1` or `t1`                                    |
    | `--read-shards`          |            | Number of shards (each shard provides 250 GB storage)                          |
    | `--read-replicas`        |            | Number of replicas for higher throughput                                       |
    | **Pod-based indexes**    |            |                                                                                |
    | `--environment`          |            | Environment of the index to create (for example, `us-east-1-aws`)              |
    | `--pod-type`             |            | Type of pod to use (for example, `p1.x1`, `s1.x2`)                             |
    | `--shards`               |            | Number of shards (default: `1`)                                                |
    | `--replicas`             |            | Number of replicas (default: `1`)                                              |
    | `--metadata-config`      |            | Comma-separated list of metadata fields to index for search                    |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Create serverless index
    pc index create -n my-index -d 1536 -m cosine -c aws -r us-east-1

    # Create sparse vector index
    pc index create -n sparse-index -m dotproduct -c aws -r us-east-1 --vector-type sparse

    # With integrated embedding model
    pc index create \
      -n my-index \
      -m cosine \
      -c aws \
      -r us-east-1 \
      --model multilingual-e5-large \
      --field-map text=chunk_text

    # With dedicated read capacity
    pc index create \
      -n my-index \
      -d 1536 \
      -m cosine \
      -c aws \
      -r us-east-1 \
      --read-mode dedicated \
      --read-node-type b1 \
      --read-shards 2 \
      --read-replicas 2

    # With deletion protection
    pc index create \
      -n my-index \
      -d 1536 \
      -m cosine \
      -c aws \
      -r us-west-2 \
      --deletion-protection enabled

    # From collection
    pc index create \
      -n my-index \
      -d 1536 \
      -m cosine \
      -c aws \
      -r eu-west-1 \
      --source-collection my-collection

    # Create pod-based index
    pc index create \
      -n my-index \
      -d 1536 \
      -m cosine \
      --environment us-east-1-aws \
      --pod-type p1.x1 \
      --shards 1 \
      --replicas 1
    ```

    <Note>
      For a list of valid regions for a serverless index, see [Create a serverless index](/guides/index-data/create-an-index).
    </Note>
  </Accordion>

  <Accordion title="pc index delete (Delete an index)">
    **Description**

    Permanently deletes an index and all its data. This operation cannot be undone.

    **Usage**

    ```bash theme={null}
    pc index delete [flags]
    ```

    **Flags**

    | Long flag             | Short flag | Description                                                |
    | :-------------------- | :--------- | :--------------------------------------------------------- |
    | `--index-name`        | `-i`       | Name of index to delete (required)                         |
    | `--skip-confirmation` |            | Skip the deletion confirmation prompt                      |
    | `--json`              | `-j`       | Output in JSON format (also skips the confirmation prompt) |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Delete an index (prompts for confirmation)
    pc index delete --index-name my-index

    # Skip the confirmation prompt
    pc index delete --index-name my-index --skip-confirmation

    # List before and after
    pc index list
    pc index delete --index-name test-index --skip-confirmation
    pc index list
    ```

    <Note>
      This command prompts for confirmation before deleting. Pass `--skip-confirmation` (or `--json`) to bypass the prompt in non-interactive contexts.
    </Note>
  </Accordion>

  <Accordion title="pc index describe (Show index details)">
    **Description**

    Displays detailed configuration and status information for a specific index.

    **Usage**

    ```bash theme={null}
    pc index describe [flags]
    ```

    **Flags**

    | Long flag      | Short flag | Description           |
    | :------------- | :--------- | :-------------------- |
    | `--index-name` | `-i`       | Index name (required) |
    | `--json`       | `-j`       | Output in JSON format |

    The `--name`/`-n` flag is a deprecated alias for `--index-name`/`-i`.

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Describe an index
    pc index describe -i my-index

    # JSON output
    pc index describe -i my-index -j

    # Check newly created index
    pc index create -n test-index -d 1536 -m cosine -c aws -r us-east-1
    pc index describe -i test-index
    ```
  </Accordion>

  <Accordion title="pc index stats (Show index statistics)">
    **Description**

    Displays statistics for an index, including total vector count and namespace breakdown. Optionally filter results with a metadata filter.

    **Usage**

    ```bash theme={null}
    pc index stats [flags]
    ```

    **Flags**

    | Long flag      | Short flag | Description                                                    |
    | :------------- | :--------- | :------------------------------------------------------------- |
    | `--index-name` | `-i`       | Index name (required)                                          |
    | `--filter`     | `-f`       | Metadata filter (inline JSON, `./path.json`, or `-` for stdin) |
    | `--json`       | `-j`       | Output in JSON format                                          |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Get stats for an index
    pc index stats -i my-index

    # Get stats with a metadata filter
    pc index stats -i my-index --filter '{"genre":{"$eq":"rock"}}'

    # Filter from file
    pc index stats -i my-index --filter ./filter.json

    # JSON output
    pc index stats -i my-index -j
    ```
  </Accordion>

  <Accordion title="pc index list (List all indexes)">
    **Description**

    Displays all indexes in your current target project, including various details.

    **Usage**

    ```bash theme={null}
    pc index list [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description                                         |
    | :-------- | :--------- | :-------------------------------------------------- |
    | `--json`  | `-j`       | Output in JSON format (includes full index details) |
    | `--wide`  | `-w`       | Show additional columns (host, embed, tags)         |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # List all indexes
    pc index list

    # Show additional details
    pc index list --wide

    # JSON output for scripting
    pc index list -j

    # After creating indexes
    pc index create -n test-1 -d 768 -m cosine -c aws -r us-east-1
    pc index list
    ```
  </Accordion>
</AccordionGroup>

### Namespaces

<AccordionGroup>
  <Accordion title="pc index namespace create (Create a namespace)">
    **Description**

    Creates a new namespace within an index. Namespaces allow you to partition vectors within an index.

    **Usage**

    ```bash theme={null}
    pc index namespace create [flags]
    ```

    **Flags**

    | Long flag      | Short flag | Description                                         |
    | :------------- | :--------- | :-------------------------------------------------- |
    | `--index-name` | `-i`       | Index name (required)                               |
    | `--name`       |            | Namespace name (required)                           |
    | `--schema`     |            | Metadata schema for the namespace (comma-separated) |
    | `--json`       | `-j`       | Output in JSON format                               |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Create a namespace
    pc index namespace create -i my-index --name tenant-a

    # Create with metadata schema (comma-separated list of filterable metadata fields)
    pc index namespace create -i my-index --name tenant-b --schema "category,brand"

    # JSON output
    pc index namespace create -i my-index --name tenant-c -j
    ```
  </Accordion>

  <Accordion title="pc index namespace delete (Delete a namespace)">
    **Description**

    Deletes a namespace and all its vectors from an index. This operation cannot be undone.

    **Usage**

    ```bash theme={null}
    pc index namespace delete [flags]
    ```

    **Flags**

    | Long flag             | Short flag | Description                                                            |
    | :-------------------- | :--------- | :--------------------------------------------------------------------- |
    | `--index-name`        | `-i`       | Index name (required)                                                  |
    | `--name`              |            | Namespace name (required); use `__default__` for the default namespace |
    | `--skip-confirmation` |            | Skip the deletion confirmation prompt                                  |
    | `--json`              | `-j`       | Output in JSON format (also skips the confirmation prompt)             |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Delete a namespace (prompts for confirmation)
    pc index namespace delete -i my-index --name tenant-a

    # Delete the default namespace
    pc index namespace delete -i my-index --name __default__

    # Skip the confirmation prompt
    pc index namespace delete -i my-index --name tenant-a --skip-confirmation
    ```

    <Warning>
      Deleting a namespace removes all vectors in that namespace. This operation cannot be undone.
    </Warning>
  </Accordion>

  <Accordion title="pc index namespace describe (Show namespace details)">
    **Description**

    Displays detailed information about a specific namespace, including record count and schema configuration.

    **Usage**

    ```bash theme={null}
    pc index namespace describe [flags]
    ```

    **Flags**

    | Long flag      | Short flag | Description                                                            |
    | :------------- | :--------- | :--------------------------------------------------------------------- |
    | `--index-name` | `-i`       | Index name (required)                                                  |
    | `--name`       |            | Namespace name (required); use `__default__` for the default namespace |
    | `--json`       | `-j`       | Output in JSON format                                                  |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Describe a namespace
    pc index namespace describe -i my-index --name tenant-a

    # Describe the default namespace
    pc index namespace describe -i my-index --name __default__

    # JSON output
    pc index namespace describe -i my-index --name tenant-a -j
    ```
  </Accordion>

  <Accordion title="pc index namespace list (List namespaces)">
    **Description**

    Lists all namespaces within an index, including vector counts.

    **Usage**

    ```bash theme={null}
    pc index namespace list [flags]
    ```

    **Flags**

    | Long flag            | Short flag | Description                    |
    | :------------------- | :--------- | :----------------------------- |
    | `--index-name`       | `-i`       | Index name (required)          |
    | `--limit`            | `-l`       | Maximum number of results      |
    | `--pagination-token` | `-p`       | Pagination token for next page |
    | `--prefix`           |            | Filter namespaces by prefix    |
    | `--json`             | `-j`       | Output in JSON format          |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # List all namespaces
    pc index namespace list -i my-index

    # Filter by prefix
    pc index namespace list -i my-index --prefix "tenant-"

    # Limit results
    pc index namespace list -i my-index --limit 10

    # JSON output
    pc index namespace list -i my-index -j
    ```
  </Accordion>
</AccordionGroup>

### Vectors

<AccordionGroup>
  <Accordion title="pc index vector delete (Delete vectors)">
    **Description**

    Deletes vectors from an index by ID, filter, or deletes all vectors in a namespace.

    **Usage**

    ```bash theme={null}
    pc index vector delete [flags]
    ```

    **Flags**

    | Long flag             | Short flag | Description                                                               |
    | :-------------------- | :--------- | :------------------------------------------------------------------------ |
    | `--index-name`        | `-i`       | Index name (required)                                                     |
    | `--namespace`         |            | Namespace to delete from (default: `__default__`)                         |
    | `--ids`               |            | Vector IDs to delete (inline JSON array, `./path.json`, or `-` for stdin) |
    | `--filter`            |            | Metadata filter (inline JSON, `./path.json`, or `-` for stdin)            |
    | `--all-vectors`       |            | Delete all vectors in the namespace                                       |
    | `--skip-confirmation` |            | Skip the confirmation prompt shown for `--all-vectors`                    |
    | `--json`              | `-j`       | Output in JSON format (also skips the confirmation prompt)                |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Delete specific vectors
    pc index vector delete -i my-index --ids '["id1"]'

    # Delete multiple vectors (inline JSON array, or JSON array in a file)
    pc index vector delete -i my-index --ids '["id1", "id2"]'

    # Delete by filter
    pc index vector delete -i my-index --filter '{"genre":"classical"}'

    # Delete all vectors in a namespace (prompts for confirmation)
    pc index vector delete -i my-index --namespace old-data --all-vectors

    # Delete all vectors without the prompt
    pc index vector delete -i my-index --namespace old-data --all-vectors --skip-confirmation
    ```

    <Note>
      Only `--all-vectors` prompts for confirmation. Targeted deletes with `--ids` or `--filter` proceed without a prompt. Pass `--skip-confirmation` (or `--json`) to bypass the `--all-vectors` prompt.
    </Note>

    <Warning>
      Vector deletion is permanent and cannot be undone.
    </Warning>
  </Accordion>

  <Accordion title="pc index vector fetch (Fetch vectors by ID or filter)">
    **Description**

    Retrieves vectors by their IDs or by a metadata filter, returning the vector values and metadata.

    **Usage**

    ```bash theme={null}
    pc index vector fetch [flags]
    ```

    **Flags**

    | Long flag            | Short flag | Description                                                              |
    | :------------------- | :--------- | :----------------------------------------------------------------------- |
    | `--index-name`       | `-i`       | Index name (required)                                                    |
    | `--namespace`        |            | Namespace to fetch from (default: `__default__`)                         |
    | `--ids`              |            | Vector IDs to fetch (inline JSON array, `./path.json`, or `-` for stdin) |
    | `--filter`           | `-f`       | Metadata filter (inline JSON, `./path.json`, or `-` for stdin)           |
    | `--limit`            | `-l`       | Maximum number of vectors to fetch                                       |
    | `--pagination-token` | `-p`       | Pagination token for next page                                           |
    | `--body`             |            | Request body JSON (inline, `./path.json`, or `-` for stdin)              |
    | `--json`             | `-j`       | Output in JSON format                                                    |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Fetch specific vectors by ID
    pc index vector fetch -i my-index --ids '["123","456","789"]'

    # Fetch from a file
    pc index vector fetch -i my-index --ids ./ids.json

    # Fetch by metadata filter
    pc index vector fetch -i my-index --filter '{"genre":{"$eq":"rock"}}'

    # Fetch from a namespace
    pc index vector fetch -i my-index --namespace tenant-a --ids '["doc-123"]'

    # JSON output
    pc index vector fetch -i my-index --ids '["vec1"]' -j
    ```

    <Note>
      Use either `--ids` or `--filter`, not both. When using `--ids`, pagination flags are not applicable.
    </Note>
  </Accordion>

  <Accordion title="pc index vector list (List vector IDs)">
    **Description**

    Lists vector IDs in a namespace with optional pagination.

    **Usage**

    ```bash theme={null}
    pc index vector list [flags]
    ```

    **Flags**

    | Long flag            | Short flag | Description                                     |
    | :------------------- | :--------- | :---------------------------------------------- |
    | `--index-name`       | `-i`       | Index name (required)                           |
    | `--namespace`        |            | Namespace to list from (default: `__default__`) |
    | `--limit`            | `-l`       | Maximum number of IDs to return                 |
    | `--pagination-token` | `-p`       | Pagination token for next page                  |
    | `--json`             | `-j`       | Output in JSON format                           |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # List vector IDs
    pc index vector list -i my-index

    # List from a namespace with limit
    pc index vector list -i my-index --namespace tenant-a --limit 50

    # JSON output
    pc index vector list -i my-index -j
    ```
  </Accordion>

  <Accordion title="pc index vector query (Query vectors)">
    **Description**

    Queries an index for similar vectors using dense vectors, sparse vectors, or vector ID.

    **Usage**

    ```bash theme={null}
    pc index vector query [flags]
    ```

    **Flags**

    | Long flag            | Short flag | Description                                                                       |
    | :------------------- | :--------- | :-------------------------------------------------------------------------------- |
    | `--index-name`       | `-i`       | Index name (required)                                                             |
    | `--namespace`        |            | Namespace to query (default: `__default__`)                                       |
    | `--id`               |            | Query by vector ID                                                                |
    | `--vector`           | `-v`       | Query vector values (inline JSON array, `./path.json`, or `-` for stdin)          |
    | `--sparse-indices`   |            | Sparse vector indices (inline JSON uint32 array, `./path.json`, or `-` for stdin) |
    | `--sparse-values`    |            | Sparse vector values (inline JSON array, `./path.json`, or `-` for stdin)         |
    | `--top-k`            | `-k`       | Number of results to return (default: 10)                                         |
    | `--filter`           | `-f`       | Metadata filter (inline JSON, `./path.json`, or `-` for stdin)                    |
    | `--include-values`   |            | Include vector values in results                                                  |
    | `--include-metadata` |            | Include metadata in results                                                       |
    | `--body`             |            | Request body JSON (inline, `./path.json`, or `-` for stdin)                       |
    | `--json`             | `-j`       | Output in JSON format                                                             |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Query by vector ID
    pc index vector query -i my-index --id "doc-123" -k 10 --include-metadata

    # Query by vector values
    pc index vector query -i my-index --vector '[0.1, 0.2, 0.3]' -k 25

    # Query with metadata filter
    pc index vector query -i my-index \
      --vector '[0.1, 0.2, 0.3]' \
      --filter '{"genre":{"$eq":"sci-fi"}}' \
      --include-metadata

    # Query from file (file contains a JSON array that specifies the query vector)
    pc index vector query -i my-index --vector ./embedding.json -k 20

    # Query with sparse vectors (inline)
    pc index vector query -i my-index \
      --sparse-indices '[0, 5, 12]' \
      --sparse-values '[0.5, 0.3, 0.8]' \
      -k 15

    # Query with sparse vectors from files
    # indices.json: [0, 5, 12]
    # values.json: [0.5, 0.3, 0.8]
    pc index vector query -i my-index \
      --sparse-indices ./indices.json \
      --sparse-values ./values.json \
      -k 15

    # Query from stdin (extract embedding from a document)
    # doc.json: {"id": "doc-123", "embedding": [0.1, 0.2, 0.3], "text": "..."}
    jq -c '.embedding' doc.json | pc index vector query -i my-index --vector - -k 10
    ```

    <Note>
      Use `--id`, `--vector`, or sparse vectors (`--sparse-indices` and `--sparse-values`) to specify what to query against. These options are mutually exclusive.
    </Note>
  </Accordion>

  <Accordion title="pc index vector update (Update vectors)">
    **Description**

    Updates a vector's values, sparse values, or metadata by ID, or updates metadata for multiple vectors matching a filter.

    **Usage**

    ```bash theme={null}
    pc index vector update [flags]
    ```

    **Flags**

    | Long flag          | Short flag | Description                                                                    |
    | :----------------- | :--------- | :----------------------------------------------------------------------------- |
    | `--index-name`     | `-i`       | Index name (required)                                                          |
    | `--namespace`      |            | Namespace containing the vector (default: `__default__`)                       |
    | `--id`             |            | Vector ID to update                                                            |
    | `--values`         |            | New vector values (inline JSON array, `./path.json`, or `-` for stdin)         |
    | `--sparse-indices` |            | New sparse indices (inline JSON uint32 array, `./path.json`, or `-` for stdin) |
    | `--sparse-values`  |            | New sparse values (inline JSON array, `./path.json`, or `-` for stdin)         |
    | `--metadata`       |            | New or updated metadata (inline JSON, `./path.json`, or `-` for stdin)         |
    | `--filter`         |            | Metadata filter for bulk update (inline JSON, `./path.json`, or `-` for stdin) |
    | `--dry-run`        |            | Preview how many records would be updated without applying changes             |
    | `--body`           |            | Request body JSON (inline, `./path.json`, or `-` for stdin)                    |
    | `--json`           | `-j`       | Output in JSON format                                                          |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Update metadata for a single vector
    pc index vector update -i my-index --id "vec1" --metadata '{"category":"updated"}'

    # Update values for a single vector
    pc index vector update -i my-index --id "vec1" --values '[0.2, 0.3, 0.4]'

    # Update sparse values
    # indices.json: [0, 5, 12]
    # values.json: [0.5, 0.3, 0.8]
    pc index vector update -i my-index --id "vec1" \
      --sparse-indices ./indices.json \
      --sparse-values ./values.json

    # Bulk update metadata by filter (preview first)
    pc index vector update -i my-index \
      --filter '{"genre":{"$eq":"sci-fi"}}' \
      --metadata '{"genre":"fantasy"}' \
      --dry-run

    # Apply the bulk update
    pc index vector update -i my-index \
      --filter '{"genre":{"$eq":"sci-fi"}}' \
      --metadata '{"genre":"fantasy"}'
    ```

    <Note>
      Use either `--id` for single vector updates or `--filter` for bulk updates. These options are mutually exclusive.
    </Note>
  </Accordion>

  <Accordion title="pc index vector upsert (Upsert vectors)">
    **Description**

    Inserts or updates vectors in an index from a JSON or JSONL file, or inline JSON. The CLI automatically batches vectors for efficient uploading. Files can contain any number of vectors—the CLI splits them into batches and sends multiple API requests as needed.

    **Usage**

    ```bash theme={null}
    pc index vector upsert [flags]
    ```

    **Flags**

    | Long flag      | Short flag | Description                                                                        |
    | :------------- | :--------- | :--------------------------------------------------------------------------------- |
    | `--index-name` | `-i`       | Index name (required)                                                              |
    | `--namespace`  |            | Namespace to upsert into (default: `__default__`)                                  |
    | `--body`       |            | Request body JSON or JSONL (inline, `./path.json[l]`, or `-` for stdin) (required) |
    | `--batch-size` | `-b`       | Size of batches to upsert (default: 500)                                           |
    | `--json`       | `-j`       | Output in JSON format                                                              |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Upsert from JSON file (with "vectors" array)
    # vectors.json: {"vectors": [{"id": "vec1", "values": [0.1, 0.2, 0.3], "metadata": {"genre": "comedy"}}]}
    pc index vector upsert -i my-index --body ./vectors.json

    # Upsert with inline JSON
    pc index vector upsert -i my-index --body '{"vectors": [{"id": "vec1", "values": [0.1, 0.2, 0.3], "metadata": {"genre": "comedy"}}]}'

    # Upsert from JSONL file (one vector per line)
    # vectors.jsonl: {"id": "vec1", "values": [0.1, 0.2, 0.3]}
    #                {"id": "vec2", "values": [0.4, 0.5, 0.6]}
    pc index vector upsert -i my-index --body ./vectors.jsonl

    # Upsert from stdin (same format as JSON or JSONL file)
    cat vectors.json | pc index vector upsert -i my-index --body -

    # Custom batch size (default: 500, max: 1000 per API request)
    pc index vector upsert -i my-index --body ./vectors.json --batch-size 1000
    ```

    <Note>
      **Batch size limits:** The API accepts up to 1000 vectors per request. The CLI defaults to batches of 500 vectors, but you can adjust this with `--batch-size` (up to 1000). Large files are automatically split into multiple batches.

      **File size:** There's no explicit file size limit—the CLI reads the entire file into memory and batches it automatically. Very large files are supported as long as they fit in available system memory.
    </Note>
  </Accordion>
</AccordionGroup>

### Records

<AccordionGroup>
  <Accordion title="pc index record search (Search records in an index)">
    **Description**

    Search an index namespace with a query text, query vector, or record ID and return the most similar records, along with their similarity scores. Optionally, rerank the initial results based on their relevance to the query.

    Searching with text is supported only for indexes with an integrated embedding configured. Searching with a query vector or record ID is supported for all indexes.

    Exactly one primary query mode must be provided:

    * `--inputs` — query text (requires an index with integrated embedding)
    * `--id` — use an existing record's vector as the query
    * `--vector` — provide a dense vector directly (all index types)
    * `--sparse-indices` + `--sparse-values` — sparse vector (all index types)

    Combine `--vector` with `--sparse-indices`/`--sparse-values` for hybrid search. Use `--body` to pass a full request object; flags take precedence over `--body` when both specify the same field.

    **Usage**

    ```bash theme={null}
    pc index record search [flags]
    ```

    **Flags**

    | Long flag          | Short flag | Description                                                                                                                                                     |
    | :----------------- | :--------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `--index-name`     | `-i`       | Name of the index to search (required)                                                                                                                          |
    | `--inputs`         |            | Query inputs for text search (inline JSON, `./path.json`, or `-` for stdin); requires integrated embedding. Mutually exclusive with `--id` and `--vector`.      |
    | `--id`             |            | Use an existing record's vector by ID for the query. Mutually exclusive with `--inputs` and `--vector`.                                                         |
    | `--vector`         | `-v`       | Dense vector values to search against (inline JSON float32 array, `./path.json`, or `-` for stdin). Mutually exclusive with `--inputs` and `--id`.              |
    | `--sparse-indices` |            | Sparse vector indices (inline JSON int32 array, `./path.json`, or `-` for stdin). Must be used together with `--sparse-values`.                                 |
    | `--sparse-values`  |            | Sparse vector values (inline JSON float32 array, `./path.json`, or `-` for stdin). Must be used together with `--sparse-indices`.                               |
    | `--top-k`          | `-k`       | Number of results to return (required)                                                                                                                          |
    | `--namespace`      |            | Namespace to search                                                                                                                                             |
    | `--filter`         |            | Metadata filter (inline JSON, `./path.json`, or `-` for stdin)                                                                                                  |
    | `--rerank`         |            | Re-score results using an inference model (inline JSON, `./path.json`, or `-` for stdin). Required fields: `model` (string), `rank_fields` (string array).      |
    | `--match-terms`    |            | Keyword terms filter for sparse integrated indexes (inline JSON, `./path.json`, or `-` for stdin). Required field: `terms` (string array). Requires `--inputs`. |
    | `--fields`         |            | Fields to return in results (inline JSON string array, `./path.json`, or `-` for stdin)                                                                         |
    | `--body`           |            | Full request body JSON (inline, `./path.json`, or `-` for stdin). Flags take precedence when both specify the same field.                                       |
    | `--json`           | `-j`       | Output in JSON format                                                                                                                                           |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Examples**

    ```bash theme={null}
    # Text search (integrated embedding indexes only)
    pc index record search --index-name my-index --inputs '{"text":"disease prevention"}' --top-k 10
    pc index record search --index-name my-index --inputs '{"text":"disease prevention"}' --namespace my-namespace --top-k 5
    pc index record search --index-name my-index --inputs '{"text":"disease prevention"}' --filter '{"category":"health"}' --top-k 10
    pc index record search --index-name my-index --inputs '{"text":"disease prevention"}' --fields '["_id","chunk_text","category"]' --top-k 10
    pc index record search --index-name my-index --inputs '{"text":"disease prevention"}' --rerank '{"model":"bge-reranker-v2-m3","rank_fields":["chunk_text"]}' --top-k 10
    pc index record search --index-name my-index --inputs '{"text":"disease prevention"}' --match-terms '{"terms":["vaccine","prevention"]}' --top-k 10

    # Search by record ID for query vector (all index types)
    pc index record search --index-name my-index --id rec-123 --top-k 10

    # Vector search (all index types)
    pc index record search --index-name my-index --vector '[0.1,0.2,0.3]' --top-k 10
    pc index record search --index-name my-index --sparse-indices '[1,5,9]' --sparse-values '[0.4,0.8,0.2]' --top-k 10
    pc index record search --index-name my-index --vector '[0.1,0.2,0.3]' --sparse-indices '[1,5,9]' --sparse-values '[0.4,0.8,0.2]' --top-k 10

    # Full request body (must include top_k in the body)
    pc index record search --index-name my-index --body ./search.json
    ```

    ```text CLI theme={null}
    Usage: 5 (read units)
    ID          SCORE       FIELDS
    rec-001     0.912340    {"category":"health","chunk_text":"vaccine research..."}
    rec-002     0.887210    {"category":"health","chunk_text":"disease prevention..."}
    ```
  </Accordion>

  <Accordion title="pc index record upsert (Upsert records into an integrated index)">
    **Description**

    Upsert records into an integrated index namespace from a JSON or JSONL payload.

    The `--body` flag accepts a JSON object containing a `"records"` array of `IntegratedRecord` objects, a raw JSON array of records, or a JSONL stream of records (one object per line). The value can be inline JSON, a path to a `.json` or `.jsonl` file, or `-` to read from stdin.

    Records are sent in batches. The default batch size is 96 (the API maximum). Use `--batch-size` to send smaller batches.

    **Usage**

    ```bash theme={null}
    pc index record upsert [flags]
    ```

    **Flags**

    | Long flag      | Short flag | Description                                                                             |
    | :------------- | :--------- | :-------------------------------------------------------------------------------------- |
    | `--index-name` | `-i`       | Name of the index to upsert into (required)                                             |
    | `--body`       |            | Request body JSON or JSONL (inline JSON, `./path.json[l]`, or `-` for stdin) (required) |
    | `--namespace`  |            | Namespace to upsert into                                                                |
    | `--batch-size` | `-b`       | Number of records per batch (default: `96`, max: `96`)                                  |
    | `--json`       | `-j`       | Output in JSON format                                                                   |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Examples**

    ```bash theme={null}
    # Upsert from a JSON file
    pc index record upsert --index-name my-index --body ./records.json

    # Upsert from a JSONL file into a specific namespace
    pc index record upsert --index-name my-index --namespace my-namespace --body ./records.jsonl

    # Upsert from stdin
    cat records.jsonl | pc index record upsert --index-name my-index --namespace my-namespace --body -
    ```
  </Accordion>
</AccordionGroup>

### Collections

<AccordionGroup>
  <Accordion title="pc index collection create (Create a collection from a pod-based index)">
    **Description**

    Creates a static copy of a pod-based index as a collection. Collections can be used to store a snapshot of an index's data for backup or migration purposes.

    **Usage**

    ```bash theme={null}
    pc index collection create [flags]
    ```

    **Flags**

    | Long flag  | Short flag | Description                                                 |
    | :--------- | :--------- | :---------------------------------------------------------- |
    | `--name`   | `-n`       | Name to give the collection (required)                      |
    | `--source` | `-s`       | Name of the pod-based index to use as the source (required) |
    | `--json`   | `-j`       | Output in JSON format                                       |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Create a collection from a pod-based index
    pc index collection create --name my-collection --source my-index
    ```

    ```text CLI theme={null}
    ATTRIBUTE     VALUE
    Name          my-collection
    State         Initializing
    Dimension     1536
    Size          0
    VectorCount   0
    Environment   us-east-1-aws
    ```
  </Accordion>

  <Accordion title="pc index collection delete (Delete a collection)">
    **Description**

    Deletes a collection permanently. This action cannot be undone.

    **Usage**

    ```bash theme={null}
    pc index collection delete [flags]
    ```

    **Flags**

    | Long flag             | Short flag | Description                                                |
    | :-------------------- | :--------- | :--------------------------------------------------------- |
    | `--name`              | `-n`       | Name of the collection to delete (required)                |
    | `--skip-confirmation` |            | Skip the deletion confirmation prompt                      |
    | `--json`              | `-j`       | Output in JSON format (also skips the confirmation prompt) |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Delete a collection (prompts for confirmation)
    pc index collection delete --name my-collection

    # Skip the confirmation prompt
    pc index collection delete --name my-collection --skip-confirmation
    ```

    <Note>
      This command prompts for confirmation before deleting. Pass `--skip-confirmation` (or `--json`) to bypass the prompt in non-interactive contexts.
    </Note>
  </Accordion>

  <Accordion title="pc index collection describe (Describe a collection by name)">
    **Description**

    Returns detailed information about a single collection, including its state, dimension, size, vector count, and environment.

    **Usage**

    ```bash theme={null}
    pc index collection describe [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description                                   |
    | :-------- | :--------- | :-------------------------------------------- |
    | `--name`  | `-n`       | Name of the collection to describe (required) |
    | `--json`  | `-j`       | Output in JSON format                         |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Describe a collection
    pc index collection describe --name my-collection
    ```

    ```text CLI theme={null}
    ATTRIBUTE     VALUE
    Name          my-collection
    State         Ready
    Dimension     1536
    Size          104857600
    VectorCount   10000
    Environment   us-east-1-aws
    ```
  </Accordion>

  <Accordion title="pc index collection list (List collections in your project)">
    **Description**

    Lists all collections in your current project, sorted alphabetically by name.

    **Usage**

    ```bash theme={null}
    pc index collection list [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description           |
    | :-------- | :--------- | :-------------------- |
    | `--json`  | `-j`       | Output in JSON format |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # List all collections
    pc index collection list
    ```

    ```text CLI theme={null}
    NAME             DIMENSION   SIZE        STATUS   VECTORS   ENVIRONMENT
    my-collection    1536        104857600   Ready    10000     us-east-1-aws
    ```
  </Accordion>
</AccordionGroup>

### Backups

<AccordionGroup>
  <Accordion title="pc index backup create (Create a backup)">
    **Description**

    Creates a backup of a serverless index. Backups are static copies that only consume storage.

    **Usage**

    ```bash theme={null}
    pc index backup create [flags]
    ```

    **Flags**

    | Long flag       | Short flag | Description                                                          |
    | :-------------- | :--------- | :------------------------------------------------------------------- |
    | `--index-name`  | `-i`       | Name of the index to back up (required)                              |
    | `--name`        |            | Human-readable label for the backup (the backup ID is always a UUID) |
    | `--description` | `-d`       | Description for the backup                                           |
    | `--json`        | `-j`       | Output in JSON format                                                |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Create a backup
    pc index backup create -i my-index

    # Create with name and description
    pc index backup create -i my-index --name "nightly-backup" -d "Nightly backup before deployment"

    # JSON output
    pc index backup create -i my-index -j
    ```
  </Accordion>

  <Accordion title="pc index backup delete (Delete a backup)">
    **Description**

    Permanently deletes a backup. This operation cannot be undone.

    **Usage**

    ```bash theme={null}
    pc index backup delete [flags]
    ```

    **Flags**

    | Long flag             | Short flag | Description                                                |
    | :-------------------- | :--------- | :--------------------------------------------------------- |
    | `--id`                | `-i`       | Backup ID to delete (required)                             |
    | `--skip-confirmation` |            | Skip the deletion confirmation prompt                      |
    | `--json`              | `-j`       | Output in JSON format (also skips the confirmation prompt) |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Delete a backup by ID (prompts for confirmation)
    pc index backup delete -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f

    # Skip the confirmation prompt
    pc index backup delete -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f --skip-confirmation
    ```

    <Note>
      This command prompts for confirmation before deleting. Pass `--skip-confirmation` (or `--json`) to bypass the prompt in non-interactive contexts.
    </Note>

    <Warning>
      Backup deletion is permanent and cannot be undone.
    </Warning>
  </Accordion>

  <Accordion title="pc index backup describe (Show backup details)">
    **Description**

    Displays detailed information about a specific backup.

    **Usage**

    ```bash theme={null}
    pc index backup describe [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description                      |
    | :-------- | :--------- | :------------------------------- |
    | `--id`    | `-i`       | Backup ID to describe (required) |
    | `--json`  | `-j`       | Output in JSON format            |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Describe a backup
    pc index backup describe -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f

    # JSON output
    pc index backup describe -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f -j
    ```
  </Accordion>

  <Accordion title="pc index backup list (List backups)">
    **Description**

    Lists backups in the current project, optionally filtered by index name.

    **Usage**

    ```bash theme={null}
    pc index backup list [flags]
    ```

    **Flags**

    | Long flag            | Short flag | Description                    |
    | :------------------- | :--------- | :----------------------------- |
    | `--index-name`       | `-i`       | Filter backups by index name   |
    | `--limit`            | `-l`       | Maximum number of results      |
    | `--pagination-token` | `-p`       | Pagination token for next page |
    | `--json`             | `-j`       | Output in JSON format          |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # List all backups in the project
    pc index backup list

    # List backups for a specific index
    pc index backup list --index-name my-index

    # Limit results
    pc index backup list --limit 10

    # JSON output
    pc index backup list -j
    ```
  </Accordion>

  <Accordion title="pc index restore (Restore an index from a backup)">
    **Description**

    Creates a new index from a backup.

    **Usage**

    ```bash theme={null}
    pc index restore [flags]
    ```

    **Flags**

    | Long flag               | Short flag | Description                                          |
    | :---------------------- | :--------- | :--------------------------------------------------- |
    | `--id`                  | `-i`       | Backup ID (UUID) to restore from (required)          |
    | `--name`                | `-n`       | Name for the new index (required)                    |
    | `--deletion-protection` |            | Enable deletion protection - `enabled` or `disabled` |
    | `--tags`                | `-t`       | Tags to apply to the new index (key=value pairs)     |
    | `--json`                | `-j`       | Output in JSON format                                |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Restore an index from a backup
    pc index restore -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f -n restored-index

    # Restore with tags and deletion protection
    pc index restore -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f -n restored-index \
      --tags env=prod,team=search \
      --deletion-protection enabled

    # JSON output
    pc index restore -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f -n restored-index -j
    ```
  </Accordion>

  <Accordion title="pc index restore describe (Show restore job details)">
    **Description**

    Displays the status and details of a restore job.

    **Usage**

    ```bash theme={null}
    pc index restore describe [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description                           |
    | :-------- | :--------- | :------------------------------------ |
    | `--id`    | `-i`       | Restore job ID to describe (required) |
    | `--json`  | `-j`       | Output in JSON format                 |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Describe a restore job
    pc index restore describe -i rj-abc123

    # JSON output
    pc index restore describe -i rj-abc123 -j
    ```
  </Accordion>

  <Accordion title="pc index restore list (List restore jobs)">
    **Description**

    Lists all restore jobs in the current project.

    **Usage**

    ```bash theme={null}
    pc index restore list [flags]
    ```

    **Flags**

    | Long flag            | Short flag | Description                    |
    | :------------------- | :--------- | :----------------------------- |
    | `--limit`            | `-l`       | Maximum number of results      |
    | `--pagination-token` | `-p`       | Pagination token for next page |
    | `--json`             | `-j`       | Output in JSON format          |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # List restore jobs
    pc index restore list

    # Limit results
    pc index restore list --limit 10

    # JSON output
    pc index restore list -j
    ```
  </Accordion>
</AccordionGroup>

### Imports

<AccordionGroup>
  <Accordion title="pc index import start (Start an import from a storage URI)">
    **Description**

    Start an import that loads vector data from a storage provider into a serverless index. The URI must begin with the scheme of a supported provider (for example, `s3://`).

    For private buckets, configure a storage integration in the Pinecone console and pass the integration ID with `--integration-id`.

    Use `--error-mode` to control behavior when records fail: `continue` skips failing records and keeps going; `abort` stops the import on first error. Defaults to `continue`.

    **Usage**

    ```bash theme={null}
    pc index import start [flags]
    ```

    **Flags**

    | Long flag          | Short flag | Description                                                           |
    | :----------------- | :--------- | :-------------------------------------------------------------------- |
    | `--index-name`     | `-i`       | Name of the index to import into (required)                           |
    | `--uri`            | `-u`       | URI of the data to import, for example `s3://bucket/path/` (required) |
    | `--integration-id` |            | Storage integration ID for private buckets                            |
    | `--error-mode`     |            | How to handle record errors: `continue` (default) or `abort`          |
    | `--json`           | `-j`       | Output in JSON format                                                 |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Examples**

    ```bash theme={null}
    # Start an import from a public S3 bucket
    pc index import start --index-name my-index --uri s3://my-bucket/data/

    # Start an import from a private bucket using a storage integration
    pc index import start --index-name my-index --uri s3://my-bucket/data/ --integration-id intg-123

    # Abort on the first error instead of continuing
    pc index import start --index-name my-index --uri s3://my-bucket/data/ --error-mode abort

    # JSON output
    pc index import start --index-name my-index --uri s3://my-bucket/data/ -j
    ```

    ```text CLI theme={null}
    Import imp-abc123 started.
    ATTRIBUTE    VALUE
    Import ID    imp-abc123
    ```
  </Accordion>

  <Accordion title="pc index import describe (Describe an import operation)">
    **Description**

    Show the current status and details of an import operation, including
    percent complete, records imported, and any error messages.

    **Usage**

    ```bash theme={null}
    pc index import describe [flags]
    ```

    **Flags**

    | Long flag      | Short flag | Description                                        |
    | :------------- | :--------- | :------------------------------------------------- |
    | `--index-name` | `-i`       | Name of the index the import belongs to (required) |
    | `--id`         |            | ID of the import to describe (required)            |
    | `--json`       | `-j`       | Output in JSON format                              |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Describe an import operation
    pc index import describe --index-name my-index --id import-123

    # JSON output
    pc index import describe --index-name my-index --id import-123 -j
    ```

    ```text CLI theme={null}
    ATTRIBUTE         VALUE
    Import ID         import-123
    Status            InProgress
    URI               s3://my-bucket/data/
    Percent Complete  45.0%
    Records Imported  450
    Created At        2024-01-15 12:00:00
    Finished At       -
    Error             None
    ```
  </Accordion>

  <Accordion title="pc index import list (List import operations for an index)">
    **Description**

    List bulk import operations for the given index, with optional pagination.

    **Usage**

    ```bash theme={null}
    pc index import list [flags]
    ```

    **Flags**

    | Long flag            | Short flag | Description                                               |
    | :------------------- | :--------- | :-------------------------------------------------------- |
    | `--index-name`       | `-i`       | Name of the index to list imports for (required)          |
    | `--limit`            | `-l`       | Maximum number of imports to return                       |
    | `--pagination-token` | `-p`       | Pagination token to continue a previous listing operation |
    | `--json`             | `-j`       | Output in JSON format                                     |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Examples**

    ```bash theme={null}
    # List all imports for an index
    pc index import list --index-name my-index

    # List imports with a page size limit
    pc index import list --index-name my-index --limit 10

    # Continue paginating from a previous call
    pc index import list --index-name my-index --pagination-token eyJ...

    # JSON output
    pc index import list --index-name my-index -j
    ```

    ```text CLI theme={null}
    IMPORT ID     STATUS      URI                     PERCENT  RECORDS  CREATED              FINISHED
    imp-abc123    Completed   s3://my-bucket/data/    100.0%   1000     2024-01-15 12:00:00  2024-01-15 12:05:00
    imp-def456    InProgress  s3://other-bucket/data/ 45.0%    450      2024-01-15 13:00:00  -
    ```
  </Accordion>

  <Accordion title="pc index import cancel (Cancel an in-progress import operation)">
    **Description**

    Cancel an import operation that is currently pending or in progress.
    Already-completed or failed imports cannot be canceled.

    **Usage**

    ```bash theme={null}
    pc index import cancel [flags]
    ```

    **Flags**

    | Long flag      | Short flag | Description                                        |
    | :------------- | :--------- | :------------------------------------------------- |
    | `--index-name` | `-i`       | Name of the index the import belongs to (required) |
    | `--id`         |            | ID of the import to cancel (required)              |
    | `--json`       | `-j`       | Output in JSON format                              |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Cancel an import operation
    pc index import cancel --index-name my-index --id import-123

    # JSON output
    pc index import cancel --index-name my-index --id import-123 -j
    ```

    ```text CLI theme={null}
    Import import-123 canceled.
    ```
  </Accordion>
</AccordionGroup>

### Projects

<AccordionGroup>
  <Accordion title="pc project create (Create a new project)">
    **Description**

    Creates a new project in your [target organization](/reference/cli/target-context), using the specified configuration.

    **Usage**

    ```bash theme={null}
    pc project create [flags]
    ```

    **Flags**

    | Long flag            | Short flag | Description                                                    |
    | :------------------- | :--------- | :------------------------------------------------------------- |
    | `--force-encryption` |            | Enable encryption with CMEK                                    |
    | `--json`             | `-j`       | Output in JSON format                                          |
    | `--name`             | `-n`       | Project name (required)                                        |
    | `--target`           |            | Automatically target the project in the CLI after it's created |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Basic project creation
    pc project create -n "demo-project"
    ```
  </Accordion>

  <Accordion title="pc project delete (Delete a project)">
    **Description**

    Permanently deletes a project and all its resources. This operation cannot be undone.

    **Usage**

    ```bash theme={null}
    pc project delete [flags]
    ```

    **Flags**

    | Long flag             | Short flag | Description                                                 |
    | :-------------------- | :--------- | :---------------------------------------------------------- |
    | `--id`                | `-i`       | Project ID (optional, uses target project if not specified) |
    | `--json`              | `-j`       | Output in JSON format                                       |
    | `--skip-confirmation` |            | Skip confirmation prompt                                    |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Delete target project
    pc project delete

    # Delete specific project
    pc project delete -i proj-abc123

    # Skip confirmation
    pc project delete -i proj-abc123 --skip-confirmation
    ```

    <Note>
      Must delete all indexes and collections in the project first. If the deleted project is your current target, set a new target after deleting it.
    </Note>
  </Accordion>

  <Accordion title="pc project describe (Show project details)">
    **Description**

    Displays detailed information about a specific project, including various details.

    **Usage**

    ```bash theme={null}
    pc project describe [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description           |
    | :-------- | :--------- | :-------------------- |
    | `--id`    | `-i`       | Project ID (required) |
    | `--json`  | `-j`       | Output in JSON format |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Describe a project
    pc project describe -i proj-abc123

    # JSON output
    pc project describe -i proj-abc123 --json

    # Find ID and describe
    pc project list
    pc project describe -i proj-abc123
    ```
  </Accordion>

  <Accordion title="pc project list (List all projects)">
    **Description**

    Displays all projects in your [target organization](/reference/cli/target-context), including various details.

    **Usage**

    ```bash theme={null}
    pc project list [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description           |
    | :-------- | :--------- | :-------------------- |
    | `--json`  | `-j`       | Output in JSON format |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # List all projects
    pc project list

    # JSON output
    pc project list --json

    # List after login
    pc auth login
    pc auth target -o "my-org"
    pc project list
    ```
  </Accordion>

  <Accordion title="pc project update (Update project settings)">
    **Description**

    Modifies the configuration of the [target project](/reference/cli/target-context), or a specific project ID.

    **Usage**

    ```bash theme={null}
    pc project update [flags]
    ```

    **Flags**

    | Long flag            | Short flag | Description                         |
    | :------------------- | :--------- | :---------------------------------- |
    | `--force-encryption` | `-f`       | Enable/disable encryption with CMEK |
    | `--id`               | `-i`       | Project ID (required)               |
    | `--json`             | `-j`       | Output in JSON format               |
    | `--name`             | `-n`       | New project name                    |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Update name
    pc project update -i proj-abc123 -n "new-name"
    ```
  </Accordion>
</AccordionGroup>

### Organizations

<AccordionGroup>
  <Accordion title="pc organization delete (Delete an organization)">
    **Description**

    Permanently deletes an organization and all its resources. This operation cannot be undone.

    **Usage**

    ```bash theme={null}
    pc organization delete [flags]
    ```

    **Flags**

    | Long flag             | Short flag | Description                |
    | :-------------------- | :--------- | :------------------------- |
    | `--id`                | `-i`       | Organization ID (required) |
    | `--json`              | `-j`       | Output in JSON format      |
    | `--skip-confirmation` |            | Skip confirmation prompt   |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Delete an organization
    pc organization delete -i org-abc123

    # Skip confirmation
    pc organization delete -i org-abc123 --skip-confirmation
    ```

    <Note>
      This is a highly destructive action. Deletion is permanent. If the deleted organization is your current [target](/reference/cli/target-context), set a new target after deleting.
    </Note>
  </Accordion>

  <Accordion title="pc organization describe (Show organization details)">
    **Description**

    Displays detailed information about a specific organization, including name, ID, creation date, payment status, plan, and support tier.

    **Usage**

    ```bash theme={null}
    pc organization describe [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description                |
    | :-------- | :--------- | :------------------------- |
    | `--id`    | `-i`       | Organization ID (required) |
    | `--json`  | `-j`       | Output in JSON format      |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Describe an organization
    pc organization describe -i org-abc123

    # JSON output
    pc organization describe -i org-abc123 --json

    # Find ID and describe
    pc organization list
    pc organization describe -i org-abc123
    ```
  </Accordion>

  <Accordion title="pc organization list (List organizations)">
    **Description**

    Displays all organizations that the authenticated user has access to, including name, ID, creation date, payment status, plan, and support tier.

    **Usage**

    ```bash theme={null}
    pc organization list [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description           |
    | :-------- | :--------- | :-------------------- |
    | `--json`  | `-j`       | Output in JSON format |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # List all organizations
    pc organization list

    # JSON output
    pc organization list --json

    # List after login
    pc auth login
    pc organization list
    ```
  </Accordion>

  <Accordion title="pc organization update (Update organization settings)">
    **Description**

    Modifies the configuration of the [target organization](/reference/cli/target-context), or a specific organization ID.

    **Usage**

    ```bash theme={null}
    pc organization update [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description                |
    | :-------- | :--------- | :------------------------- |
    | `--id`    | `-i`       | Organization ID (required) |
    | `--json`  | `-j`       | Output in JSON format      |
    | `--name`  | `-n`       | New organization name      |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Update name
    pc organization update -i org-abc123 -n "new-name"

    # Verify changes
    pc organization update -i org-abc123 -n "Acme Corp"
    pc organization describe -i org-abc123
    ```
  </Accordion>
</AccordionGroup>

### API keys

<AccordionGroup>
  <Accordion title="pc api-key create (Create a new API key)">
    **Description**

    Creates a new API key for the current [target project](/reference/cli/target-context) or a specific project ID. Optionally stores the key locally for CLI use.

    **Usage**

    ```bash theme={null}
    pc api-key create [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description                                                                             |
    | :-------- | :--------- | :-------------------------------------------------------------------------------------- |
    | `--id`    | `-i`       | Project ID (optional, uses target project if not specified)                             |
    | `--json`  | `-j`       | Output in JSON format                                                                   |
    | `--name`  | `-n`       | Key name (required)                                                                     |
    | `--roles` |            | Roles to assign (default: `ProjectEditor`)                                              |
    | `--store` |            | Store the key locally for CLI use (automatically replaces any existing CLI-managed key) |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Basic key creation
    pc api-key create -n "my-key"

    # Create and store locally
    pc api-key create -n "my-key" --store

    # Create with specific role
    pc api-key create -n "my-key" --store --roles ProjectEditor

    # Create for specific project
    pc api-key create -n "my-key" -i proj-abc123
    ```

    <Note>
      API keys are scoped to a specific organization and project.
    </Note>
  </Accordion>

  <Accordion title="pc api-key delete (Delete an API key)">
    **Description**

    Permanently deletes an API key. Applications using this key immediately lose access.

    **Usage**

    ```bash theme={null}
    pc api-key delete [flags]
    ```

    **Flags**

    | Long flag             | Short flag | Description              |
    | :-------------------- | :--------- | :----------------------- |
    | `--id`                | `-i`       | API key ID (required)    |
    | `--skip-confirmation` |            | Skip confirmation prompt |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Delete an API key
    pc api-key delete -i key-abc123

    # Skip confirmation
    pc api-key delete -i key-abc123 --skip-confirmation

    # Delete and clean up local storage
    pc api-key delete -i key-abc123
    pc auth local-keys prune --skip-confirmation
    ```

    <Note>
      Deletion is permanent. Applications using this key immediately lose access to Pinecone.
    </Note>
  </Accordion>

  <Accordion title="pc api-key describe (Show API key details)">
    **Description**

    Displays detailed information about a specific API key, including its name, ID, project ID, and roles.

    **Usage**

    ```bash theme={null}
    pc api-key describe [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description           |
    | :-------- | :--------- | :-------------------- |
    | `--id`    | `-i`       | API key ID (required) |
    | `--json`  | `-j`       | Output in JSON format |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Describe an API key
    pc api-key describe -i key-abc123

    # JSON output
    pc api-key describe -i key-abc123 --json

    # Find ID and describe
    pc api-key list
    pc api-key describe -i key-abc123
    ```

    <Note>
      Does not display the actual key value.
    </Note>
  </Accordion>

  <Accordion title="pc api-key list (List all API keys)">
    **Description**

    Displays a list of all of the [target project's](/reference/cli/target-context) API keys, as found in  Pinecone (regardless of whether they are stored locally by the CLI). Displays various details about each key, including name, ID, project ID, and roles.

    **Usage**

    ```bash theme={null}
    pc api-key list [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description                                                 |
    | :-------- | :--------- | :---------------------------------------------------------- |
    | `--id`    | `-i`       | Project ID (optional, uses target project if not specified) |
    | `--json`  | `-j`       | Output in JSON format                                       |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # List keys for target project
    pc api-key list

    # List for specific project
    pc api-key list -i proj-abc123

    # JSON output
    pc api-key list --json
    ```

    <Note>
      Does not display key values.
    </Note>
  </Accordion>

  <Accordion title="pc api-key update (Update API key settings)">
    **Description**

    Updates the name and roles of an API key.

    **Usage**

    ```bash theme={null}
    pc api-key update [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description           |
    | :-------- | :--------- | :-------------------- |
    | `--id`    | `-i`       | API key ID (required) |
    | `--json`  | `-j`       | Output in JSON format |
    | `--name`  | `-n`       | New key name          |
    | `--roles` | `-r`       | Roles to assign       |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Update name
    pc api-key update -i key-abc123 -n "new-name"

    # Update roles
    pc api-key update -i key-abc123 -r ProjectEditor

    # Verify changes
    pc api-key update -i key-abc123 -n "production-key"
    pc api-key describe -i key-abc123
    ```

    <Note>
      Cannot change the actual key. If you need a different key, create a new one.
    </Note>
  </Accordion>
</AccordionGroup>

### Config

<AccordionGroup>
  <Accordion title="pc config list (List all configuration settings and their current values)">
    **Description**

    Lists all CLI configuration settings and their current values. Sensitive values like `api-key` are masked by default; use `--reveal` to see the full value. Hidden settings such as `environment` are included when `--all` is passed.

    **Usage**

    ```bash theme={null}
    pc config list [flags]
    ```

    **Flags**

    | Long flag  | Short flag | Description                                               |
    | :--------- | :--------- | :-------------------------------------------------------- |
    | `--reveal` |            | Reveal the full value for sensitive settings like api-key |
    | `--json`   | `-j`       | Output in JSON format                                     |
    | `--all`    |            | Include hidden settings such as environment               |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    pc config list
    pc config list --all
    pc config list --reveal
    pc config list --json
    ```

    ```text CLI theme={null}
    KEY         VALUE             ENV VAR NAME        ENV VAR OVERRIDE  DESCRIPTION
    api-key     ****abcd****      PINECONE_API_KEY     false             Default API key for authenticating with Pinecone
    color       true                                                     Enable colored output
    ```
  </Accordion>

  <Accordion title="pc config get <key> (Get the current value of a configuration setting)">
    **Description**

    Gets the current value of a configuration setting. Valid keys are: `api-key`, `color`, `environment`. Sensitive values like `api-key` are masked by default; use `--reveal` to see the full value.

    **Usage**

    ```bash theme={null}
    pc config get <key> [flags]
    ```

    **Flags**

    | Long flag  | Short flag | Description                                               |
    | :--------- | :--------- | :-------------------------------------------------------- |
    | `--reveal` |            | Reveal the full value for sensitive settings like api-key |
    | `--json`   | `-j`       | Output in JSON format                                     |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    pc config get api-key
    pc config get api-key --reveal
    pc config get environment
    pc config get color
    ```
  </Accordion>

  <Accordion title="pc config describe <key> (Show detailed information about a configuration setting)">
    **Description**

    Displays detailed information about a specific CLI configuration setting, including its current value, whether an environment variable is overriding it, and valid values. Valid keys are: `api-key`, `color`, `environment`.

    **Usage**

    ```bash theme={null}
    pc config describe <key> [flags]
    ```

    **Flags**

    | Long flag  | Short flag | Description                                               |
    | :--------- | :--------- | :-------------------------------------------------------- |
    | `--reveal` |            | Reveal the full value for sensitive settings like api-key |
    | `--json`   | `-j`       | Output in JSON format                                     |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    pc config describe api-key
    pc config describe color
    pc config describe color --json
    ```

    ```text CLI theme={null}
    KEY               api-key
    VALUE             ****abcd****
    ENV VAR NAME      $PINECONE_API_KEY
    ENV VAR OVERRIDE  false
    SENSITIVE         true
    DESCRIPTION       Default API key for authenticating with Pinecone
    ```
  </Accordion>

  <Accordion title="pc config set <key> <value> (Set a configuration value)">
    **Description**

    Sets a CLI configuration value. Valid keys are: `api-key`, `color`, `environment`. The value is persisted to the local config file.

    **Usage**

    ```bash theme={null}
    pc config set <key> <value> [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description           |
    | :-------- | :--------- | :-------------------- |
    | `--json`  | `-j`       | Output in JSON format |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    pc config set api-key pcsk_...
    pc config set environment staging
    pc config set color false
    ```
  </Accordion>

  <Accordion title="pc config unset <key> (Reset a configuration value to its default)">
    **Description**

    Resets a CLI configuration value to its default. Valid keys are: `api-key`, `color`, `environment`.

    **Usage**

    ```bash theme={null}
    pc config unset <key> [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description           |
    | :-------- | :--------- | :-------------------- |
    | `--json`  | `-j`       | Output in JSON format |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    pc config unset api-key
    pc config unset color
    ```
  </Accordion>
</AccordionGroup>


# CLI quickstart
Source: https://docs.pinecone.io/reference/cli/quickstart

Pinecone CLI quickstart for installing pc, authenticating, and managing indexes, vectors, and data imports directly from your terminal.

The Pinecone CLI (`pc`) lets you manage Pinecone resources directly from your terminal.

## Install

<Tabs>
  <Tab title="macOS (Homebrew)">
    ```bash theme={null}
    brew tap pinecone-io/tap
    brew install pinecone-io/tap/pinecone
    ```
  </Tab>

  <Tab title="Other platforms">
    Pre-built binaries for macOS, Linux, and Windows are available on the [GitHub Releases page](https://github.com/pinecone-io/cli/releases).

    | Platform | Architectures                          |
    | :------- | :------------------------------------- |
    | macOS    | Intel (x86\_64), Apple Silicon (ARM64) |
    | Linux    | x86\_64, ARM64, i386                   |
    | Windows  | x86\_64, i386                          |
  </Tab>
</Tabs>

## Authenticate

```bash theme={null}
pc auth login
```

Visit the URL in your terminal to sign in. The CLI automatically sets your default organization and project.

To target a different org/project:

```bash theme={null}
pc target -o "my-org" -p "my-project"
```

<Tip>
  For CI/CD or automation, you can also authenticate with a [service account](/reference/cli/authentication#service-account) or [API key](/reference/cli/authentication#api-key).
</Tip>

## Manage indexes

```bash theme={null}
# List indexes
pc index list

# Create an index
pc index create -n my-index -d 3 -m cosine -c aws -r us-east-1

# Get index details
pc index describe -i my-index

# Get index statistics
pc index stats -i my-index
```

## Work with vectors

```bash theme={null}
# Upsert vectors (from file or inline JSON)
pc index vector upsert -i my-index \
  --body '{"vectors": [{"id": "vec1", "values": [0.1, 0.2, 0.3], "metadata": {"genre": "comedy"}}]}'

# Import from a large dataset in object storage (S3, GCS, Azure)
pc index import start -i my-index --uri s3://my-bucket/data/

# Check the progress of an import operation
pc index import list --i my-index
pc index import describe --i my-index --id import-123

# Query (vector can be inline or in a file)
pc index vector query -i my-index \
  --vector '[0.1, 0.2, 0.3]' \
  --top-k 10 \
  --include-metadata

# Fetch by ID (from file or inline JSON)
pc index vector fetch -i my-index --ids '["vec1","vec2"]'

# List vector IDs from an index
pc index vector list -i my-index
```

## Manage namespaces

```bash theme={null}
# List namespaces
pc index namespace list -i my-index

# Create a namespace
pc index namespace create -i my-index --name tenant-a

# Delete a namespace
pc index namespace delete -i my-index --name tenant-a
```

## Back up and restore

```bash theme={null}
# Create a backup
pc index backup create -i my-index --name "my-index-backup"

# List backups (show index, backup name, backup ID, etc.)
pc index backup list -i my-index

# Restore from backup (by ID, not name)
pc index restore -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f -n restored-index
```

## JSON output

Add `-j` to any command for JSON output:

```bash theme={null}
pc index list -j
pc index describe -i my-index -j
```

## Getting help

Use `-h` or `--help` with any command to see available options:

```bash theme={null}
pc -h
pc index -h
pc index create -h
```

## Next steps

* [Command reference](/reference/cli/command-reference) — Full list of commands and flags
* [Authentication](/reference/cli/authentication) — Service accounts, API keys, and auth priority
* [Target context](/reference/cli/target-context) — How org/project targeting works


# CLI target context
Source: https://docs.pinecone.io/reference/cli/target-context

Pinecone CLI: The CLI's **target context** determines which organization and project your commands operate on. You must authenticate before setting target.

The CLI's **target context** determines which organization and project your commands operate on. You must [authenticate](/reference/cli/authentication) before setting target context.

## Flags

| Flag                | Short | Default | Description                                                                       |
| ------------------- | ----- | ------- | --------------------------------------------------------------------------------- |
| `--org`             | `-o`  | —       | Target organization by name. Mutually exclusive with `--organization-id`.         |
| `--organization-id` | —     | —       | Target organization by ID. Mutually exclusive with `--org`.                       |
| `--project`         | `-p`  | —       | Target project by name. Mutually exclusive with `--project-id`.                   |
| `--project-id`      | —     | —       | Target project by ID. Mutually exclusive with `--project`.                        |
| `--show`            | `-s`  | `false` | Show the current target context.                                                  |
| `--clear`           | —     | `false` | Clear the stored target context.                                                  |
| `--json`            | `-j`  | `false` | Output as JSON. In non-TTY environments (CI/CD, pipes), JSON output is automatic. |

<Note>
  `--org` and `--organization-id` are mutually exclusive — use one or the other. The same applies to `--project` and `--project-id`.
</Note>

## How operations use target context

| Operation type                   | Scope                                    |
| -------------------------------- | ---------------------------------------- |
| Control plane (indexes, backups) | Target project                           |
| Data plane (vectors, namespaces) | Target project + specified index         |
| Admin API (organizations)        | No target context needed                 |
| Admin API (projects)             | Target organization                      |
| Admin API (API keys)             | Target project (unless `--id` specified) |

## Target context by auth method

### User login

After `pc auth login`, the CLI auto-targets your default organization and its first project.

```bash theme={null}
# Change target
pc target -o "my-org" -p "my-project"
```

### Service account

**Via CLI command:** After `pc auth configure --client-id --client-secret`, the CLI auto-targets the service account's organization. For the project:

* If one project exists, it's auto-targeted
* If multiple exist, you're prompted (or use `--project-id`)
* If none exist, create one and target it manually

**Via environment variables:** If using `PINECONE_CLIENT_ID` and `PINECONE_CLIENT_SECRET` without running `pc auth configure`, no target context is set automatically. Run `pc target` to set it.

```bash theme={null}
# Change project (org is fixed to the service account's org)
pc target -p "my-project"

# Or select interactively
pc target
```

### API key

<Warning>
  When using an API key, control plane and data plane operations use the **key's org/project scope**, not the CLI's stored target context. The `pc target --show` output does not reflect what these operations actually use.
</Warning>

API keys are scoped to a specific org and project and cannot access resources outside that scope.

Admin API operations still use your user login or service account credentials (API keys can't authenticate Admin API calls).

## Managing target context

```bash theme={null}
pc target --show   # View current target
pc target --clear  # Clear target context
```

### JSON mode and non-TTY environments

Running `pc target --json` with no targeting flags returns the current target context as a JSON object. This is a local-state read — **no authentication is required**:

```bash theme={null}
pc target --json
```

In non-TTY environments (CI/CD pipelines, shell pipes, scripts), JSON output is automatic — the same as passing `--json` explicitly. You do not need to add the flag in automation contexts.

Use `--organization-id` and `--project-id` (instead of name flags) to set context reliably in scripts, since IDs are stable and unaffected by renames:

```bash theme={null}
pc target --organization-id "org-abc123" --project-id "proj-xyz789" --json
```


# Pinecone SDKs overview
Source: https://docs.pinecone.io/reference/pinecone-sdks

Browse official Pinecone SDKs for Python, Node.js, Java, and Go, including the version mappings between SDK releases and API versions.

## Pinecone SDKs

Official Pinecone SDKs provide convenient access to the [Pinecone APIs](/reference/api/introduction).

<CardGroup>
  <Card title="Python SDK" icon="python" href="/reference/sdks/python/overview" />

  <Card title="Node.js SDK" icon="node-js" href="/reference/sdks/node/overview" />

  <Card title="Java SDK" icon="java" href="/reference/sdks/java/overview" />

  <Card title="Go SDK" icon="golang" href="/reference/sdks/go/overview" />
</CardGroup>

## SDK versions

SDK versions are pinned to specific [API versions](/reference/api/versioning). When a new API version is released, a new version of the SDK is also released.

The mappings between API versions and SDK versions are as follows:

|                                               | `2026-04`   | `2025-10` | `2025-04` | `2025-01` | `2024-10` | `2024-07`     | `2024-04` |
| --------------------------------------------- | :---------- | :-------- | :-------- | :-------- | :-------- | :------------ | :-------- |
| [Python SDK](/reference/sdks/python/overview) | v9.x        | v8.x      | v7.x      | v6.x      | v5.3.x    | v5.0.x-v5.2.x | v4.x      |
| [Node.js SDK](/reference/sdks/node/overview)  | v8.x        | v7.x      | v6.x      | v5.x      | v4.x      | v3.x          | v2.x      |
| [Java SDK](/reference/sdks/java/overview)     | Coming soon | v6.x      | v5.x      | v4.x      | v3.x      | v2.x          | v1.x      |
| [Go SDK](/reference/sdks/go/overview)         | v6.x        | v5.x      | v4.x      | v3.x      | v2.x      | v1.x          | v0.x      |

When a new stable API version is released, you should upgrade your SDK to the latest version to ensure compatibility with the latest API changes.

<Note>
  The Java SDK targeting API version `2026-04` will be available soon.
</Note>

## Limitations

While Pinecone tracks read unit usage with decimal precision, the Pinecone API and SDKs round these values up to the nearest whole number in query, fetch, and list responses. For example, if a query uses 0.45 read units, the API and SDKs will report it as 1 read unit.

For precise read unit reporting, see [index-level metrics](/guides/production/monitoring) or the organization-wide [Usage dashboard](/guides/manage-cost/monitor-usage-and-costs#monitor-organization-level-usage-and-costs).

## Community SDKs

Find community-contributed SDKs for Pinecone. These libraries are not supported by Pinecone.

* [Ruby SDK](https://github.com/ScotterC/pinecone) (contributed by [ScotterC](https://github.com/ScotterC))

* [Scala SDK](https://github.com/cequence-io/pinecone-scala) (contributed by [cequence-io](https://github.com/cequence-io))

* [PHP SDK](https://github.com/probots-io/pinecone-php) (contributed by [protobots-io](https://github.com/probots-io))


# Pinecone Go SDK
Source: https://docs.pinecone.io/reference/sdks/go/overview

Install and use the Pinecone Go SDK to manage indexes and namespaces, upsert vectors, run semantic search, and call the Admin and Inference APIs from Go.

<Tip>
  For installation instructions and usage examples, see the [Go SDK documentation](https://github.com/pinecone-io/go-pinecone). To report an issue or request a feature, [file an issue on GitHub](https://github.com/pinecone-io/go-pinecone/issues).
</Tip>

## Requirements

The Pinecone Go SDK requires a Go version with [modules](https://go.dev/wiki/Modules) support.

## SDK versions

SDK versions are pinned to specific [API versions](/reference/api/versioning). When a new API version is released, a new version of the SDK is also released.

The mappings between API versions and Go SDK versions are as follows:

| API version | SDK version |
| :---------- | :---------- |
| `2026-04`   | v6.x        |
| `2025-10`   | v5.x        |
| `2025-04`   | v4.x        |
| `2025-01`   | v3.x        |
| `2024-10`   | v2.x        |
| `2024-07`   | v1.x        |
| `2024-04`   | v0.x        |

When a new stable API version is released, you should upgrade your SDK to the latest version to ensure compatibility with the latest API changes.

## Install

To install the latest version of the [Go SDK](https://github.com/pinecone-io/go-pinecone), add a dependency to the current module:

```shell theme={null}
go get github.com/pinecone-io/go-pinecone/v6/pinecone
```

To install a specific version of the Go SDK, run the following command:

```shell theme={null}
go get github.com/pinecone-io/go-pinecone/v6/pinecone@<version>
```

To check your SDK version, run the following command:

```shell theme={null}
go list -u -m all | grep go-pinecone
```

## Upgrade

<Warning>
  Before upgrading to `v3.0.0` or later, update all relevant code to account for the breaking changes explained [here](/release-notes/2025#2025-02-07-4).
</Warning>

Each major version carries its version number in the module path, so crossing a major requires updating the import path in every file that uses the SDK. For example, moving from `v4` to `v6` means changing:

```go theme={null}
// before
import "github.com/pinecone-io/go-pinecone/v4/pinecone"

// after
import "github.com/pinecone-io/go-pinecone/v6/pinecone"
```

Apart from the module path, `v5.0.0` and `v6.0.0` are backward compatible with the release lines before them.

If you already have the Go SDK, upgrade to the latest version as follows:

```shell theme={null}
go get -u github.com/pinecone-io/go-pinecone/v6/pinecone@latest
```

## Initialize

Once installed, you can import the SDK and then use an [API key](/guides/production/security-overview#api-keys) to initialize a client instance:

```Go theme={null}
package main

import (
    "context"
    "log"

    "github.com/pinecone-io/go-pinecone/v6/pinecone"
)

func main() {
    ctx := context.Background()

    pc, err := pinecone.NewClient(pinecone.NewClientParams{
        ApiKey: "YOUR_API_KEY",
    })
    if err != nil {
        log.Fatalf("Failed to create Client: %v", err)
    }
} 
```

To manage organizations, projects, API keys, and [role-based access control](/guides/production/manage-rbac), initialize an `AdminClient` with [service account](/guides/organizations/manage-service-accounts) credentials instead:

```Go theme={null}
package main

import (
    "context"
    "log"
    "os"

    "github.com/pinecone-io/go-pinecone/v6/pinecone"
)

func main() {
    ctx := context.Background()

    adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
        ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
        ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
    })
    if err != nil {
        log.Fatalf("Failed to create AdminClient: %v", err)
    }
}
```


# Reference
Source: https://docs.pinecone.io/reference/sdks/go/reference

Reference documentation for the Pinecone Go SDK, including client setup, types, and methods for managing indexes and vector data operations.



# OpenTelemetry support
Source: https://docs.pinecone.io/reference/sdks/java/open-telemetry

Monitor Pinecone Java SDK operations with OpenTelemetry metrics for client latency, server processing time, and errors via Prometheus.

The Pinecone Java SDK provides built-in support for capturing per-operation response metadata, making it straightforward to monitor your Pinecone usage with [OpenTelemetry](https://opentelemetry.io/) or any other observability system.

With this feature, you can track client-side latency, server processing time, network overhead, error rates, and more for every data plane operation your application makes.

## How it all fits together

The SDK's observability support is designed to be flexible. You don't need to adopt the entire observability stack at once -- start simple and add layers as your needs grow.

Here are the components involved and how they relate to each other:

* **Pinecone Java SDK**: Exposes a `ResponseMetadataListener` callback, a plain Java interface with no external dependencies. At its simplest, you can log the metadata to the console. No additional tools required.
* **[OpenTelemetry](https://opentelemetry.io/) (OTel)**: An open standard and SDK for producing structured telemetry data (metrics, traces, logs). If you want standardized metrics that follow [semantic conventions](https://opentelemetry.io/docs/specs/semconv/database/database-spans/), you add the OTel SDK and wire it to the listener. This is optional.
* **OTel Collector**: A vendor-neutral service that receives telemetry from your app and forwards it to a storage backend. Optional -- many setups export directly from the app to a backend.
* **Prometheus**: A time-series database that stores metrics, making them queryable over time. One popular storage option.
* **Grafana**: A visualization and dashboarding tool that queries Prometheus (or other backends) and displays charts and alerts. One popular visualization option.

A common setup chains these together:

```
Your App (OTel SDK) → OTel Collector → Prometheus (storage) → Grafana (visualization)
```

<Note>
  This is just one example pipeline. You can substitute Datadog, New Relic, or any OTel-compatible backend. You can also skip OTel entirely and use [Micrometer](#example-micrometerprometheus), custom logging, or any approach that suits your stack.
</Note>

## Response metadata listener

The Java SDK captures response metadata through a `ResponseMetadataListener` -- a functional interface you provide when building the Pinecone client. The listener is called after each data plane operation completes (whether it succeeds or fails), and receives a `ResponseMetadata` object containing timing, status, and context information.

The SDK itself has no OpenTelemetry dependency. You bring your own observability library and decide what to do with the metadata.

### Supported operations

The following data plane operations are instrumented, for both synchronous (`Index`) and asynchronous (`AsyncIndex`) usage:

| Operation | Description                |
| --------- | -------------------------- |
| `upsert`  | Insert or update vectors   |
| `query`   | Search for similar vectors |
| `fetch`   | Retrieve vectors by ID     |
| `update`  | Update vector metadata     |
| `delete`  | Delete vectors             |

### Available metadata

Each `ResponseMetadata` object provides the following fields:

| Method                   | Description                                        | OTel attribute            |
| ------------------------ | -------------------------------------------------- | ------------------------- |
| `getOperationName()`     | Operation type (e.g., `upsert`, `query`)           | `db.operation.name`       |
| `getIndexName()`         | Pinecone index name                                | `pinecone.index_name`     |
| `getNamespace()`         | Namespace (empty string if default)                | `db.namespace`            |
| `getServerAddress()`     | Pinecone server host                               | `server.address`          |
| `getClientDurationMs()`  | Total round-trip time in ms (always available)     | --                        |
| `getServerDurationMs()`  | Server processing time in ms (may be `null`)       | --                        |
| `getNetworkOverheadMs()` | Client minus server duration in ms (may be `null`) | --                        |
| `getStatus()`            | `"success"` or `"error"`                           | `status`                  |
| `getGrpcStatusCode()`    | Raw gRPC status code (e.g., `OK`, `UNAVAILABLE`)   | `db.response.status_code` |
| `getErrorType()`         | Error category, or `null` if successful            | `error.type`              |

Possible `errorType` values: `validation`, `connection`, `server`, `rate_limit`, `timeout`, `auth`, `not_found`, `unknown`.

### Recommended metrics

If you're recording OTel metrics, the SDK example project uses these metric names, which follow [OTel semantic conventions for database clients](https://opentelemetry.io/docs/specs/semconv/database/database-spans/):

| Metric                                | Type      | Unit | Description                     |
| ------------------------------------- | --------- | ---- | ------------------------------- |
| `db.client.operation.duration`        | Histogram | ms   | Client-measured round-trip time |
| `pinecone.server.processing.duration` | Histogram | ms   | Server processing time          |
| `db.client.operation.count`           | Counter   | --   | Total number of operations      |

## Quick start: Simple logging

The simplest way to use the listener is to log the metadata directly. This requires no additional dependencies beyond the Pinecone SDK:

```java theme={null}
import io.pinecone.clients.Pinecone;

Pinecone client = new Pinecone.Builder("PINECONE_API_KEY")
    .withResponseMetadataListener(metadata -> {
        System.out.printf("Operation: %s | Client: %dms | Server: %sms | Network: %sms | Status: %s%n",
            metadata.getOperationName(),
            metadata.getClientDurationMs(),
            metadata.getServerDurationMs(),
            metadata.getNetworkOverheadMs(),
            metadata.getStatus());
    })
    .build();
```

Once configured, every data plane operation automatically triggers the listener:

```java theme={null}
Index index = client.getIndexConnection("my-index");
index.upsert("id-1", Arrays.asList(0.1f, 0.2f, 0.3f));
// Output: Operation: upsert | Client: 47ms | Server: 40ms | Network: 7ms | Status: success
```

## Quick start: OpenTelemetry integration

To record structured metrics with OpenTelemetry, add the OTel SDK dependencies and wire a metrics recorder to the listener.

### 1. Add dependencies

Add the following to your `pom.xml`:

```xml theme={null}
<dependencies>
    <!-- Pinecone SDK -->
    <dependency>
        <groupId>io.pinecone</groupId>
        <artifactId>pinecone-client</artifactId>
        <version>LATEST</version>
    </dependency>

    <!-- OpenTelemetry SDK -->
    <dependency>
        <groupId>io.opentelemetry</groupId>
        <artifactId>opentelemetry-sdk</artifactId>
    </dependency>
    <dependency>
        <groupId>io.opentelemetry</groupId>
        <artifactId>opentelemetry-sdk-metrics</artifactId>
    </dependency>

    <!-- OTLP exporter (sends metrics to an OTel Collector or compatible backend) -->
    <dependency>
        <groupId>io.opentelemetry</groupId>
        <artifactId>opentelemetry-exporter-otlp</artifactId>
    </dependency>
</dependencies>

<!-- Use the OTel BOM to manage versions -->
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.opentelemetry</groupId>
            <artifactId>opentelemetry-bom</artifactId>
            <version>1.35.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
```

### 2. Create a metrics recorder

The SDK's [example project](https://github.com/pinecone-io/pinecone-java-client/tree/main/examples/java-otel-metrics) includes a reusable `PineconeMetricsRecorder` class you can copy into your project. It implements `ResponseMetadataListener` and records all three recommended metrics with proper OTel attributes:

```java theme={null}
import io.opentelemetry.api.common.AttributeKey;
import io.opentelemetry.api.common.Attributes;
import io.opentelemetry.api.common.AttributesBuilder;
import io.opentelemetry.api.metrics.LongCounter;
import io.opentelemetry.api.metrics.LongHistogram;
import io.opentelemetry.api.metrics.Meter;
import io.pinecone.configs.ResponseMetadata;
import io.pinecone.configs.ResponseMetadataListener;

public class PineconeMetricsRecorder implements ResponseMetadataListener {

    private static final AttributeKey<String> DB_SYSTEM = AttributeKey.stringKey("db.system");
    private static final AttributeKey<String> DB_OPERATION_NAME = AttributeKey.stringKey("db.operation.name");
    private static final AttributeKey<String> DB_NAMESPACE = AttributeKey.stringKey("db.namespace");
    private static final AttributeKey<String> PINECONE_INDEX_NAME = AttributeKey.stringKey("pinecone.index_name");
    private static final AttributeKey<String> SERVER_ADDRESS = AttributeKey.stringKey("server.address");
    private static final AttributeKey<String> STATUS = AttributeKey.stringKey("status");
    private static final AttributeKey<String> ERROR_TYPE = AttributeKey.stringKey("error.type");

    private final LongHistogram clientDurationHistogram;
    private final LongHistogram serverDurationHistogram;
    private final LongCounter operationCounter;

    public PineconeMetricsRecorder(Meter meter) {
        this.clientDurationHistogram = meter.histogramBuilder("db.client.operation.duration")
                .setDescription("Duration of Pinecone operations from client perspective")
                .setUnit("ms")
                .ofLongs()
                .build();

        this.serverDurationHistogram = meter.histogramBuilder("pinecone.server.processing.duration")
                .setDescription("Server processing time from x-pinecone-response-duration-ms header")
                .setUnit("ms")
                .ofLongs()
                .build();

        this.operationCounter = meter.counterBuilder("db.client.operation.count")
                .setDescription("Total number of Pinecone operations")
                .setUnit("{operation}")
                .build();
    }

    @Override
    public void onResponse(ResponseMetadata metadata) {
        AttributesBuilder attributesBuilder = Attributes.builder()
                .put(DB_SYSTEM, "pinecone")
                .put(DB_OPERATION_NAME, metadata.getOperationName())
                .put(PINECONE_INDEX_NAME, metadata.getIndexName())
                .put(SERVER_ADDRESS, metadata.getServerAddress())
                .put(STATUS, metadata.getStatus());

        String namespace = metadata.getNamespace();
        if (namespace != null && !namespace.isEmpty()) {
            attributesBuilder.put(DB_NAMESPACE, namespace);
        }

        if (!metadata.isSuccess() && metadata.getErrorType() != null) {
            attributesBuilder.put(ERROR_TYPE, metadata.getErrorType());
        }

        Attributes attributes = attributesBuilder.build();

        clientDurationHistogram.record(metadata.getClientDurationMs(), attributes);

        Long serverDuration = metadata.getServerDurationMs();
        if (serverDuration != null) {
            serverDurationHistogram.record(serverDuration, attributes);
        }

        operationCounter.add(1, attributes);
    }
}
```

### 3. Wire it into the Pinecone client

Initialize the OTel SDK, create the recorder, and pass it to the Pinecone client builder:

```java theme={null}
import io.opentelemetry.api.metrics.Meter;
import io.opentelemetry.sdk.OpenTelemetrySdk;
import io.opentelemetry.sdk.metrics.SdkMeterProvider;
import io.opentelemetry.sdk.metrics.export.PeriodicMetricReader;
import io.opentelemetry.exporter.otlp.metrics.OtlpGrpcMetricExporter;
import io.pinecone.clients.Pinecone;

// Set up OTel with OTLP exporter
OtlpGrpcMetricExporter exporter = OtlpGrpcMetricExporter.builder()
    .setEndpoint("http://localhost:4317")
    .build();

SdkMeterProvider meterProvider = SdkMeterProvider.builder()
    .registerMetricReader(PeriodicMetricReader.builder(exporter).build())
    .build();

OpenTelemetrySdk openTelemetry = OpenTelemetrySdk.builder()
    .setMeterProvider(meterProvider)
    .build();

// Create the metrics recorder
Meter meter = openTelemetry.getMeter("pinecone.client");
PineconeMetricsRecorder recorder = new PineconeMetricsRecorder(meter);

// Build the Pinecone client with the recorder
Pinecone client = new Pinecone.Builder("PINECONE_API_KEY")
    .withResponseMetadataListener(recorder)
    .build();

// Use the client normally -- metrics are recorded automatically
Index index = client.getIndexConnection("my-index");
index.upsert("id-1", Arrays.asList(0.1f, 0.2f, 0.3f));
index.query(3, Arrays.asList(0.1f, 0.2f, 0.3f));
```

<Tip>
  For a complete runnable example with Docker Compose, Prometheus, and Grafana, see the [java-otel-metrics example project](https://github.com/pinecone-io/pinecone-java-client/tree/main/examples/java-otel-metrics) in the SDK repository.
</Tip>

## Example: Micrometer/Prometheus

If your application uses [Micrometer](https://micrometer.io/) (common in Spring Boot), you can wire the listener to Micrometer instead of the OTel SDK:

```java theme={null}
import io.micrometer.core.instrument.MeterRegistry;
import io.micrometer.core.instrument.Timer;
import io.pinecone.clients.Pinecone;
import java.util.concurrent.TimeUnit;

Pinecone client = new Pinecone.Builder("PINECONE_API_KEY")
    .withResponseMetadataListener(metadata -> {
        Timer.builder("pinecone.client.duration")
            .tag("operation", metadata.getOperationName())
            .tag("index", metadata.getIndexName())
            .tag("status", metadata.getStatus())
            .register(meterRegistry)
            .record(metadata.getClientDurationMs(), TimeUnit.MILLISECONDS);
    })
    .build();
```

## Visualizing metrics

Once your metrics are flowing to a backend, you can build dashboards to monitor your Pinecone operations. If you're using Prometheus and Grafana, here are some useful queries:

**P50 and P95 client latency:**

```promql theme={null}
histogram_quantile(0.5, sum(rate(db_client_operation_duration_milliseconds_bucket[5m])) by (le))
histogram_quantile(0.95, sum(rate(db_client_operation_duration_milliseconds_bucket[5m])) by (le))
```

**P95 latency by operation type:**

```promql theme={null}
histogram_quantile(0.95, sum(rate(db_client_operation_duration_milliseconds_bucket[5m])) by (le, db_operation_name))
```

**Operation count by type:**

```promql theme={null}
sum by (db_operation_name) (db_client_operation_count_total)
```

## Understanding the latency breakdown

The `ResponseMetadata` object provides three timing values that help you pinpoint the source of latency issues:

| Component        | Method                   | What it measures                                                                                                                             |
| ---------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| Client duration  | `getClientDurationMs()`  | Total round-trip time from request start to response completion. Always available.                                                           |
| Server duration  | `getServerDurationMs()`  | Time the Pinecone backend spent processing the request. Extracted from the `x-pinecone-response-duration-ms` response header. May be `null`. |
| Network overhead | `getNetworkOverheadMs()` | The difference: client duration minus server duration. Includes network latency, serialization, and deserialization. May be `null`.          |

Use these values to diagnose performance issues:

* **High server duration**: The bottleneck is on the Pinecone backend. Consider optimizing your query (e.g., reducing `topK`, using metadata filters), or check the [Pinecone status page](https://status.pinecone.io/).
* **High network overhead**: The bottleneck is in the network path between your application and Pinecone. Consider deploying your application closer to your index's cloud region, or check for network issues.

## Limitations

* **Data plane operations only.** Control plane operations (e.g., creating or deleting indexes) are not currently instrumented.
* **Bulk import operations** are not yet instrumented.
* **Server duration may be unavailable.** The `getServerDurationMs()` method returns `null` if the `x-pinecone-response-duration-ms` header is not present in the response.
* **Synchronous callback.** The listener is called synchronously after the gRPC response is received. Keep implementations lightweight and non-blocking to avoid adding latency to your operations. For heavy processing, queue the metadata for async handling.
* **Exceptions are swallowed.** Exceptions thrown by the listener are logged but do not affect the operation result.

## Best practices

* **Keep listeners lightweight.** Record metrics or enqueue work -- don't do I/O or heavy computation in the callback.
* **Follow OTel semantic conventions.** Use the attribute names shown in the [recommended metrics](#recommended-metrics) table for interoperability with standard dashboards and tooling.
* **Monitor both client and server duration.** Tracking both lets you separate Pinecone backend performance from network conditions.
* **Set alerts on error rates.** Use the `status` and `error.type` attributes to build alerts for elevated error rates across operations.


# Pinecone Java SDK
Source: https://docs.pinecone.io/reference/sdks/java/overview

Install and use the Pinecone Java SDK to manage indexes and namespaces, upsert vectors, run semantic search, and call the Admin and Inference APIs from Java.

<Tip>
  For installation instructions and usage examples, see the [Pinecone Java SDK documentation](https://github.com/pinecone-io/pinecone-java-client). To report an issue or request a feature, [file an issue on GitHub](https://github.com/pinecone-io/pinecone-java-client/issues).
</Tip>

## Requirements

The Pinecone Java SDK requires Java 1.8 or later.

## SDK versions

SDK versions are pinned to specific [API versions](/reference/api/versioning). When a new API version is released, a new version of the SDK is also released.

The mappings between API versions and Java SDK versions are as follows:

| API version | SDK version |
| :---------- | :---------- |
| `2025-04`   | v5.x        |
| `2025-01`   | v4.x        |
| `2024-10`   | v3.x        |
| `2024-07`   | v2.x        |
| `2024-04`   | v1.x        |

When a new stable API version is released, you should upgrade your SDK to the latest version to ensure compatibility with the latest API changes.

## Install

To install the latest version of the [Java SDK](https://github.com/pinecone-io/pinecone-java-client), add a dependency to the current module:

```shell Java theme={null}
# Maven
<dependency>
  <groupId>io.pinecone</groupId>
  <artifactId>pinecone-client</artifactId>
  <version>5.0.0</version>
</dependency>

# Gradle
implementation "io.pinecone:pinecone-client:5.0.0"
```

Alternatively, you can download the standalone uberjar [pinecone-client-4.0.0-all.jar](https://repo1.maven.org/maven2/io/pinecone/pinecone-client/4.0.0/pinecone-client-4.0.0-all.jar), which bundles the Pinecone SDK and all dependencies together. You can include this in your classpath like you do with any third-party JAR without having to obtain the `pinecone-client` dependencies separately.

## Upgrade

<Warning>
  Before upgrading to `v4.0.0`, update all relevant code to account for the breaking changes explained [here](/release-notes/2025#2025-02-07-3).
</Warning>

If you are already using the Java SDK, upgrade the dependency in the current module to the latest version:

```shell Java theme={null}
# Maven
<dependency>
  <groupId>io.pinecone</groupId>
  <artifactId>pinecone-client</artifactId>
  <version>5.0.0</version>
</dependency>

# Gradle
implementation "io.pinecone:pinecone-client:5.0.0"
```

## Initialize

Once installed, you can import the SDK and then use an [API key](/guides/production/security-overview#api-keys) to initialize a client instance:

```Java theme={null}
import io.pinecone.clients.Pinecone;
import org.openapitools.db_control.client.model.*;

public class InitializeClientExample {
    public static void main(String[] args) {
        Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build();
    }
}
```

## Observability

The Java SDK supports capturing per-operation response metadata for all data plane operations, including client-side latency, server processing time, network overhead, and error details. You can use this metadata with [OpenTelemetry](https://opentelemetry.io/), Micrometer, or any other observability system to monitor your Pinecone usage in production.

For setup instructions and examples, see [OpenTelemetry support](/reference/sdks/java/open-telemetry).


# Reference
Source: https://docs.pinecone.io/reference/sdks/java/reference

Reference documentation for the Pinecone Java SDK, including client setup, types, and methods for managing indexes and vector data operations.



# Pinecone Node.js SDK
Source: https://docs.pinecone.io/reference/sdks/node/overview

Install and use the Pinecone Node.js and TypeScript SDK to manage indexes, upsert vectors, run semantic search, and call the Admin and Inference APIs.

<Tip>
  For installation instructions, usage examples, and reference information, see the [Pinecone Node.js SDK documentation](https://sdk.pinecone.io/typescript/). To report an issue or request a feature, [file an issue on GitHub](https://github.com/pinecone-io/pinecone-ts-client/issues).
</Tip>

## Requirements

The Pinecone Node SDK requires TypeScript 4.1 or later and Node 18.x or later.

## SDK versions

SDK versions are pinned to specific [API versions](/reference/api/versioning). When a new API version is released, a new version of the SDK is also released.

The mappings between API versions and Node.js SDK versions are as follows:

| API version | SDK version |
| :---------- | :---------- |
| `2026-04`   | v8.x        |
| `2025-10`   | v7.x        |
| `2025-04`   | v6.x        |
| `2025-01`   | v5.x        |
| `2024-10`   | v4.x        |
| `2024-07`   | v3.x        |
| `2024-04`   | v2.x        |

When a new stable API version is released, you should upgrade your SDK to the latest version to ensure compatibility with the latest API changes.

## Install

To install the latest version of the [Node.js SDK](https://github.com/pinecone-io/pinecone-ts-client), written in TypeScript, run the following command:

```Shell theme={null}
npm install @pinecone-database/pinecone
```

To check your SDK version, run the following command:

```Shell theme={null}
npm list | grep @pinecone-database/pinecone
```

## Upgrade

If you already have the Node.js SDK, upgrade to the latest version as follows:

```Shell theme={null}
npm install @pinecone-database/pinecone@latest
```

## Initialize

Once installed, you can import the library and then use an [API key](/guides/projects/manage-api-keys) to initialize a client instance:

```JavaScript theme={null}
import { Pinecone } from '@pinecone-database/pinecone';

const pc = new Pinecone({
    apiKey: 'YOUR_API_KEY'
});
```

To manage organizations, projects, API keys, and [role-based access control](/guides/production/manage-rbac), initialize an `AdminClient` with [service account](/guides/organizations/manage-service-accounts) credentials instead. This requires v8.2.0 or later:

```JavaScript theme={null}
import { AdminClient } from '@pinecone-database/pinecone';

// Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
const admin = new AdminClient();
```

You can also pass `clientId` and `clientSecret` directly to the constructor instead of setting environment variables.

## Proxy configuration

If your network setup requires you to interact with Pinecone through a proxy, you can pass a custom `ProxyAgent` from the [`undici` library](https://undici.nodejs.org/#/). Below is an example of how to construct an `undici` `ProxyAgent` that routes network traffic through a [`mitm` proxy server](https://mitmproxy.org/) while hitting Pinecone's `/indexes` endpoint.

<Note>
  The following strategy relies on Node's native [`fetch`](https://nodejs.org/docs/latest/api/globals.html#fetch) implementation, released in Node v16 and stabilized in Node v21. If you are running Node versions 18-21, you may experience issues stemming from the instability of the feature. There are currently no known issues related to proxying in Node v18+.
</Note>

```JavaScript JavaScript theme={null}
import {
  Pinecone,
  type PineconeConfiguration,
} from '@pinecone-database/pinecone';
import { Dispatcher, ProxyAgent } from 'undici';
import * as fs from 'fs';

const cert = fs.readFileSync('path/to/mitmproxy-ca-cert.pem');

const client = new ProxyAgent({
  uri: 'https://your-proxy.com',
  requestTls: {
    port: 'YOUR_PROXY_SERVER_PORT',
    ca: cert,
    host: 'YOUR_PROXY_SERVER_HOST',
  },
});

const customFetch = (
  input: string | URL | Request,
  init: RequestInit | undefined
) => {
  return fetch(input, {
    ...init,
    dispatcher: client as Dispatcher,
    keepalive: true,  # optional
  });
};

const config: PineconeConfiguration = {
  apiKey:
    'YOUR_API_KEY',
  fetchApi: customFetch,
};

const pc = new Pinecone(config);

const indexes = async () => {
  return await pc.listIndexes();
};

indexes().then((response) => {
  console.log('My indexes: ', response);
});
```


# Reference
Source: https://docs.pinecone.io/reference/sdks/node/reference

Reference documentation for the Pinecone Node.js SDK, including client setup, types, and methods for managing indexes and vector data operations.



# Pinecone Python SDK
Source: https://docs.pinecone.io/reference/sdks/python/overview

Install and use the Pinecone SDK for Pinecone Python SDK: auth, typed clients, and API operations. For installation instructions, usage examples, and.

<Tip>
  For installation instructions, usage examples, and reference information, see the [Pinecone Python SDK documentation](https://sdk.pinecone.io/python/). To report an issue or request a feature, [file an issue on GitHub](https://github.com/pinecone-io/pinecone-python-client/issues).
</Tip>

The Pinecone Python SDK is distributed on PyPI using the package name `pinecone`. By default, the `pinecone` package has a minimal set of dependencies and interacts with Pinecone via HTTP requests. However, you can install the following extras to unlock additional functionality:

* `pinecone[grpc]` adds dependencies on `grpcio` and related libraries needed to run data operations such as upserts and queries over [gRPC](https://grpc.io/) for a modest performance improvement.

* `pinecone[asyncio]` adds a dependency on `aiohttp` and enables usage of `async` methods for use with [asyncio](https://docs.python.org/3/library/asyncio.html). For more details, see [Async requests](#async-requests).

## Requirements

The Pinecone Python SDK requires Python 3.9 or later. It has been tested with CPython versions from 3.9 to 3.13.

## SDK versions

SDK versions are pinned to specific [API versions](/reference/api/versioning). When a new API version is released, a new version of the SDK is also released.

The mappings between API versions and Python SDK versions are as follows:

| API version | SDK version   |
| :---------- | :------------ |
| `2025-04`   | v7.x          |
| `2025-01`   | v6.x          |
| `2024-10`   | v5.3.x        |
| `2024-07`   | v5.0.x-v5.2.x |
| `2024-04`   | v4.x          |

When a new stable API version is released, you should upgrade your SDK to the latest version to ensure compatibility with the latest API changes.

## Install

To install the latest version of the [Python SDK](https://github.com/pinecone-io/pinecone-python-client), run the following command:

```shell theme={null}
# Install the latest version
pip install pinecone

# Install the latest version with gRPC extras
pip install "pinecone[grpc]"

# Install the latest version with asyncio extras
pip install "pinecone[asyncio]"
```

To install a specific version of the Python SDK, run the following command:

```shell pip theme={null}
# Install a specific version
pip install pinecone==<version>

# Install a specific version with gRPC extras
pip install "pinecone[grpc]"==<version>

# Install a specific version with asyncio extras
pip install "pinecone[asyncio]"==<version>
```

To check your SDK version, run the following command:

```shell pip theme={null}
pip show pinecone
```

<Note>
  To use the [Inference API](/reference/api/introduction#inference), you must be on version 5.0.0 or later.
</Note>

### Install the Pinecone Assistant Python plugin

As of Python SDK v7.0.0, the `pinecone-plugin-assistant` package is included by default. It is only necessary to install the package if you are using a version of the Python SDK prior to v7.0.0.

```shell HTTP theme={null}
pip install --upgrade pinecone pinecone-plugin-assistant
```

## Upgrade

<Warning>
  Before upgrading to `v6.0.0`, update all relevant code to account for the breaking changes explained [here](https://github.com/pinecone-io/pinecone-python-client/blob/main/docs/upgrading.md).

  Also, make sure to upgrade using the `pinecone` package name instead of `pinecone-client`; upgrading with the latter will not work as of `v6.0.0`.
</Warning>

If you already have the Python SDK, upgrade to the latest version as follows:

```shell theme={null}
# Upgrade to the latest version
pip install pinecone --upgrade

# Upgrade to the latest version with gRPC extras
pip install "pinecone[grpc]" --upgrade

# Upgrade to the latest version with asyncio extras
pip install "pinecone[asyncio]" --upgrade
```

## Initialize

Once installed, you can import the library and then use an [API key](/guides/projects/manage-api-keys) to initialize a client instance:

<CodeGroup>
  ```Python HTTP theme={null}
  from pinecone import Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")
  ```

  ```python gRPC theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")
  ```
</CodeGroup>

When [creating an index](/guides/index-data/create-an-index), import the `ServerlessSpec` or `PodSpec` class as well:

<CodeGroup>
  ```Python Serverless index theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone
  from pinecone import ServerlessSpec

  pc = Pinecone(api_key="YOUR_API_KEY")

  pc.create_index(
    name="docs-example",
    dimension=1536,
    metric="cosine",
    spec=ServerlessSpec(
      cloud="aws",
      region="us-east-1"
    )
  )
  ```

  ```Python Pod-based index theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone
  from pinecone import PodSpec

  pc = Pinecone(api_key="YOUR_API_KEY")

  pc.create_index(
    name="docs-example",
    dimension=1536,
    metric="cosine",
    spec=PodSpec(
      environment="us-west-1-gcp",
      pod_type="p1.x1",
      pods=1
    )
  )
  ```
</CodeGroup>

## Proxy configuration

If your network setup requires you to interact with Pinecone through a proxy, you will need to pass additional configuration using optional keyword parameters:

* `proxy_url`: The location of your proxy. This could be an HTTP or HTTPS URL depending on your proxy setup.
* `proxy_headers`: Accepts a python dictionary which can be used to pass any custom headers required by your proxy. If your proxy is protected by authentication, use this parameter to pass basic authentication headers with a digest of your username and password. The `make_headers` utility from `urllib3` can be used to help construct the dictionary. **Note:** Not supported with Asyncio.
* `ssl_ca_certs`: By default, the client will perform SSL certificate verification using the CA bundle maintained by Mozilla in the [`certifi`](https://pypi.org/project/certifi/) package. If your proxy is using self-signed certicates, use this parameter to specify the path to the certificate (PEM format).
* `ssl_verify`: SSL verification is enabled by default, but it is disabled when set to `False`. It is not recommened to go into production with SSL verification disabled.

<CodeGroup>
  ```python HTTP theme={null}
  from pinecone import Pinecone
  import urllib3
  from urllib3.util import make_headers

  pc = Pinecone(
      api_key="YOUR_API_KEY",
      proxy_url='https://your-proxy.com',
      proxy_headers=make_headers(proxy_basic_auth='username:password'),
      ssl_ca_certs='path/to/cert-bundle.pem'
  )
  ```

  ```python gRPC theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone
  import urllib3
  from urllib3.util import make_headers

  pc = Pinecone(
      api_key="YOUR_API_KEY",
      proxy_url='https://your-proxy.com',
      proxy_headers=make_headers(proxy_basic_auth='username:password'),
      ssl_ca_certs='path/to/cert-bundle.pem'
  )
  ```

  ```python asyncio theme={null}
  import asyncio
  from pinecone import PineconeAsyncio
  	
  async def main():
      async with PineconeAsyncio(
          api_key="YOUR_API_KEY",
          proxy_url='https://your-proxy.com',
          ssl_ca_certs='path/to/cert-bundle.pem'
      ) as pc:
          # Do async things
          await pc.list_indexes()

  asyncio.run(main())
  ```
</CodeGroup>

## Async requests

Pinecone Python SDK versions 6.0.0 and later provide `async` methods for use with [asyncio](https://docs.python.org/3/library/asyncio.html). Asyncio support makes it possible to use Pinecone with modern async web frameworks such as [FastAPI](https://fastapi.tiangolo.com/), [Quart](https://quart.palletsprojects.com/en/latest/), and [Sanic](https://sanic.dev/en/), and should significantly increase the efficiency of running requests in parallel.

Use the [`PineconeAsyncio`](https://sdk.pinecone.io/python/asyncio.html) class to create and manage indexes and the [`IndexAsyncio`](https://sdk.pinecone.io/python/asyncio.html#pinecone.db_data.IndexAsyncio) class to read and write index data. To ensure that sessions are properly closed, use the `async with` syntax when creating `PineconeAsyncio` and `IndexAsyncio` objects.

<CodeGroup>
  ```python Manage indexes theme={null}
  # pip install "pinecone[asyncio]"
  import asyncio
  from pinecone import PineconeAsyncio, ServerlessSpec

  async def main():
      async with PineconeAsyncio(api_key="YOUR_API_KEY") as pc:
          if not await pc.has_index(index_name):
              desc = await pc.create_index(
                  name="docs-example",
                  dimension=1536,
                  metric="cosine",
                  spec=ServerlessSpec(
                      cloud="aws",
                      region="us-east-1"
                  ),
                  deletion_protection="disabled",
                  tags={
                      "environment": "development"
                  }
              )

  asyncio.run(main())
  ```

  ```python Read and write index data theme={null}
  # pip install "pinecone[asyncio]"
  import asyncio
  from pinecone import Pinecone

  async def main():
      pc = Pinecone(api_key="YOUR_API_KEY")
      async with pc.IndexAsyncio(host="INDEX_HOST") as idx:
          await idx.upsert_records(
              namespace="example-namespace",
              records=[
                  {
                      "id": "1",
                      "title": "The Great Gatsby",
                      "author": "F. Scott Fitzgerald",
                      "description": "The story of the mysteriously wealthy Jay Gatsby and his love for the beautiful Daisy Buchanan.",
                      "year": 1925,
                  },
                  {
                      "id": "2",
                      "title": "To Kill a Mockingbird",
                      "author": "Harper Lee",
                      "description": "A young girl comes of age in the segregated American South and witnesses her father's courageous defense of an innocent black man.",
                      "year": 1960,
                  },
                  {
                      "id": "3",
                      "title": "1984",
                      "author": "George Orwell",
                      "description": "In a dystopian future, a totalitarian regime exercises absolute control through pervasive surveillance and propaganda.",
                      "year": 1949,
                  },
              ]
          )

  asyncio.run(main())
  ```
</CodeGroup>

## Query across namespaces

Each query is limited to a single [namespace](/guides/index-data/indexing-overview#namespaces). However, the Pinecone Python SDK provides a `query_namespaces` utility method to run a query in parallel across multiple namespaces in an index and then merge the result sets into a single ranked result set with the `top_k` most relevant results.

The `query_namespaces` method accepts most of the same arguments as `query` with the addition of a required `namespaces` parameter.

<Tabs>
  <Tab title="Python SDK without gRPC">
    When using the Python SDK without gRPC extras, to get good performance, it is important to set values for the `pool_threads` and `connection_pool_maxsize` properties on the index client. The `pool_threads` setting is the number of threads available to execute requests, while `connection_pool_maxsize` is the number of cached http connections that will be held. Since these tasks are not computationally heavy and are mainly i/o bound, it should be okay to have a high ratio of threads to cpus.

    The combined results include the sum of all read unit usage used to perform the underlying queries for each namespace.

    ```python Python theme={null}
    from pinecone import Pinecone

    pc = Pinecone(api_key="YOUR_API_KEY")
    index = pc.Index(
        name="docs-example",
        pool_threads=50,             # <-- make sure to set these
        connection_pool_maxsize=50,  # <-- make sure to set these
    )

    query_vec = [ 0.1, ...] # an embedding vector with same dimension as the index
    combined_results = index.query_namespaces(
        vector=query_vec,
        namespaces=['ns1', 'ns2', 'ns3', 'ns4'],
        metric="cosine",
        top_k=10,
        include_values=False,
        include_metadata=True,
        filter={"genre": { "$eq": "comedy" }},
        show_progress=False,
    )

    for scored_vec in combined_results.matches:
        print(scored_vec)
    print(combined_results.usage)
    ```
  </Tab>

  <Tab title="Python SDK with gRPC">
    When using the Python SDK with gRPC extras, there is no need to set the `connection_pool_maxsize` because grpc makes efficient use of open connections by default.

    ```python Python theme={null}
    from pinecone.grpc import PineconeGRPC

    pc = PineconeGRPC(api_key="YOUR_API_KEY")
    index = pc.Index(
        name="docs-example",
        pool_threads=50, # <-- make sure to set this
    )

    query_vec = [ 0.1, ...] # an embedding vector with same dimension as the index
    combined_results = index.query_namespaces(
        vector=query_vec,
        namespaces=['ns1', 'ns2', 'ns3', 'ns4'],
        metric="cosine",
        top_k=10,
        include_values=False,
        include_metadata=True,
        filter={"genre": { "$eq": "comedy" }},
        show_progress=False,
    )

    for scored_vec in combined_results.matches:
        print(scored_vec)
    print(combined_results.usage)
    ```
  </Tab>
</Tabs>

## Upsert from a dataframe

To quickly ingest data when using the [Python SDK](/reference/sdks/python/overview), use the `upsert_from_dataframe` method. The method includes retry logic and`batch_size`, and is performant especially with Parquet file data sets.

The following example upserts the `uora_all-MiniLM-L6-bm25` dataset as a dataframe.

```Python Python theme={null}
from pinecone import Pinecone, ServerlessSpec
from pinecone_datasets import list_datasets, load_dataset

pc = Pinecone(api_key="API_KEY")

dataset = load_dataset("quora_all-MiniLM-L6-bm25")

pc.create_index(
  name="docs-example",
  dimension=384,
  metric="cosine",
  spec=ServerlessSpec(
    cloud="aws",
    region="us-east-1"
  )
)

# To get the unique host for an index, 
# see https://docs.pinecone.io/guides/manage-data/target-an-index
index = pc.Index(host="INDEX_HOST")

index.upsert_from_dataframe(dataset.drop(columns=["blob"]))
```


# Reference
Source: https://docs.pinecone.io/reference/sdks/python/reference

Reference documentation for the Pinecone Python SDK, including client setup, types, and methods for managing indexes and vector data operations.



# Spark-Pinecone connector
Source: https://docs.pinecone.io/reference/tools/pinecone-spark-connector

Pinecone data tools: Use the connector to efficiently create, ingest, and update vector embeddings at scale with Databricks and Pinecone.

Use the [`spark-pinecone` connector](https://github.com/pinecone-io/spark-pinecone/) to efficiently create, ingest, and update [vector embeddings](https://www.pinecone.io/learn/vector-embeddings/) at scale with [Databricks and Pinecone](/integrations/databricks).

## Install the Spark-Pinecone connector

<Tabs>
  <Tab title="Databricks platform">
    1. [Install the Spark-Pinecone connector as a library](https://docs.databricks.com/en/libraries/cluster-libraries.html#install-a-library-on-a-cluster).
    2. Configure the library as follows:
       1. Select **File path/S3** as the **Library Source**.

       2. Enter the S3 URI for the Pinecone assembly JAR file:

          ```
          s3://pinecone-jars/1.1.0/spark-pinecone-uberjar.jar  
          ```

          <Note>
            Databricks platform users must use the Pinecone assembly jar listed above to ensure that the proper dependecies are installed.
          </Note>

       3. Click **Install**.
  </Tab>

  <Tab title="Databricks on AWS">
    1. [Install the Spark-Pinecone connector as a library](https://docs.databricks.com/en/libraries/cluster-libraries.html#install-a-library-on-a-cluster).
    2. Configure the library as follows:
       1. Select **File path/S3** as the **Library Source**.

       2. Enter the S3 URI for the Pinecone assembly JAR file:

          ```
          s3://pinecone-jars/1.1.0/spark-pinecone-uberjar.jar  
          ```

       3. Click **Install**.
  </Tab>

  <Tab title="Databricks on GCP / Azure">
    1. [Install the Spark-Pinecone connector as a library](https://docs.databricks.com/en/libraries/cluster-libraries.html#install-a-library-on-a-cluster).
    2. Configure the library as follows:
       1. [Download the Pinecone assembly JAR file](https://repo1.maven.org/maven2/io/pinecone/spark-pinecone_2.12/1.1.0/).
       2. Select **Workspace** as the **Library Source**.
       3. Upload the JAR file.
       4. Click **Install**.
  </Tab>
</Tabs>

## Batch upsert

To batch upsert embeddings to Pinecone:

<CodeGroup>
  ```python Python theme={null}
  from pyspark import SparkConf
  from pyspark.sql import SparkSession
  from pyspark.sql.types import StructType, StructField, ArrayType, FloatType, StringType, LongType

  # Your API key and index name
  api_key = "PINECONE_API_KEY"
  index_name = "PINECONE_INDEX_NAME"
  source_tag = "PINECONE_SOURCE_TAG"

  COMMON_SCHEMA = StructType([
      StructField("id", StringType(), False),
      StructField("namespace", StringType(), True),
      StructField("values", ArrayType(FloatType(), False), False),
      StructField("metadata", StringType(), True),
      StructField("sparse_values", StructType([
          StructField("indices", ArrayType(LongType(), False), False),
          StructField("values", ArrayType(FloatType(), False), False)
      ]), True)
  ])

  # Initialize Spark
  spark = SparkSession.builder.getOrCreate()

  # Read the file and apply the schema
  df = spark.read \
      .option("multiLine", value = True) \
      .option("mode", "PERMISSIVE") \
      .schema(COMMON_SCHEMA) \
      .json("src/test/resources/sample.jsonl")

  # Show if the read was successful
  df.show()

  # Write the dataFrame to Pinecone in batches 
  df.write \
      .option("pinecone.apiKey", api_key) \
      .option("pinecone.indexName", index_name) \
      .option("pinecone.sourceTag", source_tag) \
      .format("io.pinecone.spark.pinecone.Pinecone") \
      .mode("append") \
      .save()
  ```

  ```scala Scala theme={null}
  import io.pinecone.spark.pinecone.{COMMON_SCHEMA, PineconeOptions}
  import org.apache.spark.SparkConf
  import org.apache.spark.sql.{SaveMode, SparkSession}

  object MainApp extends App {
    // Your API key and index name
    val apiKey = "PINECONE_API_KEY"
    val indexName = "PINECONE_INDEX_NAME"
    val sourceTag = "PINECONE_SOURCE_TAG"

    // Configure Spark to run locally with all available cores
    val conf = new SparkConf()
      .setMaster("local[*]")

    // Create a Spark session with the defined configuration
    val spark = SparkSession.builder().config(conf).getOrCreate()

    // Read the JSON file into a DataFrame, applying the COMMON_SCHEMA
    val df = spark.read
      .option("multiLine", value = true)
      .option("mode", "PERMISSIVE")
      .schema(COMMON_SCHEMA)
      .json("src/test/resources/sample.jsonl") // path to sample.jsonl

    // Define Pinecone options as a Map
    val pineconeOptions = Map(
      PineconeOptions.PINECONE_API_KEY_CONF -> apiKey,
      PineconeOptions.PINECONE_INDEX_NAME_CONF -> indexName,
      PineconeOptions.PINECONE_SOURCE_TAG_CONF -> sourceTag
    )

    // Show if the read was successful
    df.show(df.count().toInt)
    
    // Write the DataFrame to Pinecone using the defined options in batches
    df.write
      .options(pineconeOptions)
      .format("io.pinecone.spark.pinecone.Pinecone")
      .mode(SaveMode.Append)
      .save()
  }
  ```
</CodeGroup>

<Tip>
  For a guide on how to set up batch upserts, refer to the [Databricks integration page](/integrations/databricks#setup-guide).
</Tip>

## Stream upsert

To stream upsert embeddings to Pinecone:

<CodeGroup>
  ```python Python theme={null}
  from pyspark.sql import SparkSession
  from pyspark.sql.types import StructType, StructField, ArrayType, FloatType, StringType, LongType
  import os

  # Your API key and index name
  api_key = "PINECONE_API_KEY"
  index_name = "PINECONE_INDEX_NAME"
  source_tag = "PINECONE_SOURCE_TAG"

  COMMON_SCHEMA = StructType([
      StructField("id", StringType(), False),
      StructField("namespace", StringType(), True),
      StructField("values", ArrayType(FloatType(), False), False),
      StructField("metadata", StringType(), True),
      StructField("sparse_values", StructType([
          StructField("indices", ArrayType(LongType(), False), False),
          StructField("values", ArrayType(FloatType(), False), False)
      ]), True)
  ])

  # Initialize Spark session
  spark = SparkSession.builder \
      .appName("StreamUpsertExample") \
      .config("spark.sql.shuffle.partitions", 3) \
      .master("local") \
      .getOrCreate()

  # Read the stream of JSON files, applying the schema from the input directory
  lines = spark.readStream \
      .option("multiLine", True) \
      .option("mode", "PERMISSIVE") \
      .schema(COMMON_SCHEMA) \
      .json("path/to/input/directory/")

  # Write the stream to Pinecone using the defined options
  upsert = lines.writeStream \
      .format("io.pinecone.spark.pinecone.Pinecone") \
      .option("pinecone.apiKey", api_key) \
      .option("pinecone.indexName", index_name) \
      .option("pinecone.sourceTag", source_tag) \
      .option("checkpointLocation", "path/to/checkpoint/dir") \
      .outputMode("append") \
      .start()

  upsert.awaitTermination()
  ```

  ```scala Scala theme={null}
  import io.pinecone.spark.pinecone.{COMMON_SCHEMA, PineconeOptions}
  import org.apache.spark.SparkConf
  import org.apache.spark.sql.{SaveMode, SparkSession}

  object MainApp extends App {
    // Your API key and index name
    val apiKey = "PINECONE_API_KEY"
    val indexName = "PINECONE_INDEX_NAME"

    // Create a Spark session
    val spark = SparkSession.builder()
      .appName("StreamUpsertExample")
      .config("spark.sql.shuffle.partitions", 3)
      .master("local")
      .getOrCreate()

    // Read the JSON files into a DataFrame, applying the COMMON_SCHEMA from input directory
    val lines = spark.readStream
      .option("multiLine", value = true)
      .option("mode", "PERMISSIVE")
      .schema(COMMON_SCHEMA)
      .json("path/to/input/directory/")

    // Define Pinecone options as a Map
    val pineconeOptions = Map(
      PineconeOptions.PINECONE_API_KEY_CONF -> System.getenv("PINECONE_API_KEY"),
      PineconeOptions.PINECONE_INDEX_NAME_CONF -> System.getenv("PINECONE_INDEX"),
      PineconeOptions.PINECONE_SOURCE_TAG_CONF -> System.getenv("PINECONE_SOURCE_TAG")
    )

    // Write the stream to Pinecone using the defined options
    val upsert = lines
      .writeStream
      .format("io.pinecone.spark.pinecone.Pinecone")
      .options(pineconeOptions)
      .option("checkpointLocation", "path/to/checkpoint/dir")
      .outputMode("append")
      .start()

    upsert.awaitTermination()
  }
  ```
</CodeGroup>

## Learn more

* [Spark-Pinecone connector setup guide](/integrations/databricks#setup-guide)
* [GitHub](https://github.com/pinecone-io/spark-pinecone)


# Authentication
Source: https://docs.pinecone.io/reference/api/authentication

Pinecone API authentication guide covering API key generation, SDK client setup, and HTTP header configuration for authorized requests.

All requests to [Pinecone APIs](/reference/api/introduction) must contain a valid [API key](/guides/production/security-overview#api-keys) for the target project.

## Get an API key

[Create a new API key](https://app.pinecone.io/organizations/-/projects/-/keys) in the Pinecone console, or use the connect widget below to generate a key.

<div>
  <div>
    <div>
      <div />
    </div>
  </div>
</div>

Copy your generated key:

```
PINECONE_API_KEY="{{YOUR_API_KEY}}"

# This API key has ReadWrite access to all indexes in your project.
```

## Initialize a client

When using a [Pinecone SDK](/reference/pinecone-sdks), initialize a client object with your API key and then reuse the authenicated client in subsquent function calls. For example:

<CodeGroup>
  ```Python Python theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone
  from pinecone import ServerlessSpec

  pc = Pinecone(api_key='YOUR_API_KEY')

  # Creates an index using the API key stored in the client 'pc'.
  pc.create_index(
      name="docs-example",
      dimension=1536,
      metric="cosine",
      spec=ServerlessSpec(
          cloud='aws', 
          region='us-east-1'
      ) 
  ) 
  ```

  ```JavaScript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone';

  const pc = new Pinecone({
      apiKey: 'YOUR_API_KEY' 
  });

  // Creates an index using the API key stored in the client 'pc'.
  await pc.createIndex({
      name: 'docs-example',
      dimension: 1536,
      metric: 'cosine',
      spec: { 
          serverless: { 
              cloud: 'aws', 
              region: 'us-east-1' 
          }
      } 
  }) 
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Pinecone;
  import org.openapitools.db_control.client.model.IndexModel;
  import org.openapitools.db_control.client.model.DeletionProtection;

  public class CreateServerlessIndexExample {
      public static void main(String[] args) {
          Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build();

          // Creates an index using the API key stored in the client 'pc'.
          pc.createServerlessIndex("docs-example", "cosine", 1536, "aws", "us-east-1");
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "fmt"
      "log"

      "github.com/pinecone-io/go-pinecone/v3/pinecone"
  )

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

  	indexName := "docs-example"
  	vectorType := "dense"
      dimension := int32(1536)
      metric := pinecone.Cosine
  	deletionProtection := pinecone.DeletionProtectionDisabled

      idx, err := pc.CreateServerlessIndex(ctx, &pinecone.CreateServerlessIndexRequest{
          Name:               indexName,
          VectorType:         &vectorType,
          Dimension:          &dimension,
          Metric:             &metric,
          Cloud:              pinecone.Aws,
          Region:             "us-east-1",
          DeletionProtection: &deletionProtection,
      })
      if err != nil {
          log.Fatalf("Failed to create serverless index: %v", err)
      } else {
          fmt.Printf("Successfully created serverless index: %v", idx.Name)
      }
  }
  ```

  ```shell curl theme={null}
  curl -s "https://api.pinecone.io/indexes" \
      -H "Api-Key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -H "X-Pinecone-Api-Version: 2025-10" \
      -d '{
          "name":  "docs-example",
          "dimension": 1536,
          "metric": "cosine",
          "spec": {
              "serverless": {
                 "cloud":"aws",
                 "region": "us-east-1"
              }
          }
      }'
  ```
</CodeGroup>

## Add headers to an HTTP request

All HTTP requests to Pinecone APIs must contain an `Api-Key` header that specifies a valid [API key](/guides/production/security-overview#api-keys) and must be encoded as JSON with the `Content-Type: application/json` header. For example:

```shell curl theme={null}
curl https://api.pinecone.io/indexes \
   -H "Content-Type: application/json" \
   -H "Api-Key: $PINECONE_API_KEY" \
  -H "X-Pinecone-Api-Version: 2025-10" \
   -d '{
         "name":  "docs-example",
         "dimension": 1536,
         "metric": "cosine",
         "spec": {
            "serverless": {
               "cloud":"aws",
               "region": "us-east-1"
            }
         }
      }'
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Initialization errors due to outdated SDKs">
    Older versions of Pinecone required you to initialize a client with an `init` method that takes both `api_key` and `environment` parameters, for example:

    <CodeGroup>
      ```python Python theme={null}
      # Legacy initialization
      import pinecone

      pc = pinecone.init(
          api_key="PINECONE_API_KEY",
          environment="PINECONE_ENVIRONMENT"
      )
      ```

      ```javascript JavaScript theme={null}
      // Legacy initialization
      import { Pinecone } from '@pinecone-database/pinecone';

      const pineconeClient = new PineconeClient();
      await pineconeClient.init({
          apiKey: 'PINECONE_API_KEY',
          environment: 'PINECONE_ENVIRONMENT',
      });
      ```
    </CodeGroup>

    In more recent versions of Pinecone, this has changed. Initialization no longer requires an `init` step, and cloud environment is defined for each index rather than an entire project. Client initialization now only requires an `api_key` parameter, for example:

    <CodeGroup>
      ```python Python theme={null}
      # New initialization
      from pinecone import Pinecone

      pc = Pinecone(api_key="YOUR_API_KEY")
      ```

      ```javascript JavaScript theme={null}
      // New initialization
      import { Pinecone } from '@pinecone-database/pinecone';

      const pc = new Pinecone({
          apiKey: 'YOUR_API_KEY' 
      });
      ```
    </CodeGroup>

    If you are receiving errors about initialization, upgrade your [Pinecone SDK](/reference/pinecone-sdks) to the latest version, for example:

    <CodeGroup>
      ```shell Python theme={null}
      # Upgrade Pinecone SDK
      pip install pinecone --upgrade
      ```

      ```shell JavaScript theme={null}
      # Upgrade Pinecone SDK
      npm install @pinecone-database/pinecone@latest
      ```
    </CodeGroup>

    Also, note that some third-party tutorials and examples still reference the older initialization method. In such cases, follow the example above and the examples throughout the Pinecone documentation instead.
  </Accordion>
</AccordionGroup>


# Pinecone Database limits
Source: https://docs.pinecone.io/reference/api/database-limits

Reference for Pinecone Database limits, covering upsert, query, fetch, delete, import, namespace, and rate limits for serverless indexes.

This page describes different types of limits for Pinecone Database.

<Note>
  **Looking for a specific limit?**

  * To compare monthly included usage by plan, start with [read units](#read-units-per-month-per-org), [write units](#write-units-per-month-per-org), and [model usage limits](#monthly-usage-limits).
  * If you received a `429` error, check [rate limits](#rate-limits), especially request-per-second limits for query, upsert, update, delete, fetch, and list.
  * For projects, users, indexes, namespaces, storage, backups, and collections, see [object limits](#object-limits).
  * For batch sizes, metadata filters, and identifier lengths, see [operation limits](#operation-limits) and [identifier limits](#identifier-limits).
</Note>

## Rate limits

Rate limits help protect your applications from misuse and maintain the health of our shared serverless infrastructure. These limits are designed to support typical production workloads while ensuring reliable performance for all users.

**Most rate limits can be adjusted upon request.** If you need higher limits to scale your application, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) with details about your use case. Pinecone is committed to supporting your growth and can often accommodate higher throughput requirements.

Rate limits vary based on [pricing plan](https://www.pinecone.io/pricing/) and apply to [serverless indexes](/guides/index-data/indexing-overview) only.

<Note>
  Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide.
</Note>

### Data plane operations: request-per-second limits

Pinecone enforces rate limits on the number of API requests per second at the namespace level for data plane operations (query, upsert, delete, and update). These limits provide protection against excessive request rates.

#### Affected operations

The following operations are subject to request-per-second rate limiting:

| Operation | Scope         | Limit |
| --------- | ------------- | ----- |
| Query     | Per namespace | 100   |
| Upsert    | Per namespace | 100   |
| Delete    | Per namespace | 100   |
| Update    | Per namespace | 100   |

#### Error response

When you exceed the request-per-second limit, you'll receive an HTTP `429 - TOO_MANY_REQUESTS` response. The error message indicates which operation exceeded the limit and includes the namespace name and limit value. See the individual limit sections below for specific error message formats.

#### How request-per-second limits work with limits on read and write units

Request-per-second limits are enforced in addition to existing read unit and write unit limits. Requests must not exceed any applicable limits:

* Index-level limits - read and write unit limits, per index
* Namespace-level limits - read and write unit limits, per namespace
* Request-per-second limits - requests per second, per namespace

If any limit is exceeded, the request fails with a 429 error.

#### Recommendations

If you're hitting request-per-second limits:

1. Implement retry logic. Use exponential backoff to handle rate limit errors gracefully. See [Error Handling Guide](/guides/production/error-handling#implement-retry-logic).
2. Pace your requests. Add client-side rate limiting to stay under limits.
3. Consider [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes), which don't have request-per-second limits and provide dedicated capacity for high-throughput workloads.
4. If you need higher limits, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) with details about your use case.

### All rate limits

#### Monthly usage limits

| Metric                                                                        | Starter plan   | Builder plan   | Standard plan  | Enterprise plan |
| :---------------------------------------------------------------------------- | :------------- | :------------- | :------------- | :-------------- |
| [Read units per month per org](#read-units-per-month-per-org)                 | 1,000,000      | 2,000,000      | Unlimited      | Unlimited       |
| [Write units per month per org](#write-units-per-month-per-org)               | 2,000,000      | 5,000,000      | Unlimited      | Unlimited       |
| [Embedding tokens per month per model](#embedding-tokens-per-month-per-model) | 5,000,000      | 10,000,000     | Unlimited      | Unlimited       |
| [Rerank requests per month per model](#rerank-requests-per-month-per-model)   | Model-specific | Model-specific | Model-specific | Model-specific  |

#### Data operation throughput limits

| Metric                                                                                                        | Starter plan | Builder plan | Standard plan | Enterprise plan |
| :------------------------------------------------------------------------------------------------------------ | :----------- | :----------- | :------------ | :-------------- |
| [Upsert size per second per namespace](#upsert-size-per-second-per-namespace)                                 | 50 MB        | 50 MB        | 50 MB         | 50 MB           |
| [Query read units per second per index](#query-read-units-per-second-per-index)                               | 2,000        | 2,000        | 2,000         | 2,000           |
| [Query requests per second per namespace](#query-requests-per-second-per-namespace)                           | 100          | 100          | 100           | 100             |
| [Update records per second per namespace](#update-records-per-second-per-namespace)                           | 100          | 100          | 100           | 100             |
| [Update requests per second per namespace](#update-requests-per-second-per-namespace)                         | 100          | 100          | 100           | 100             |
| [Update by metadata requests per second per namespace](#update-by-metadata-requests-per-second-per-namespace) | 5            | 5            | 5             | 5               |
| [Update by metadata requests per second per index](#update-by-metadata-requests-per-second-per-index)         | 500          | 500          | 500           | 500             |
| [Upsert requests per second per namespace](#upsert-requests-per-second-per-namespace)                         | 100          | 100          | 100           | 100             |
| [Fetch requests per second per index](#fetch-requests-per-second-per-index)                                   | 100          | 100          | 100           | 100             |
| [List requests per second per index](#list-requests-per-second-per-index)                                     | 200          | 200          | 200           | 200             |
| [Describe index stats requests per second per index](#describe-index-stats-requests-per-second-per-index)     | 100          | 100          | 100           | 100             |
| [Delete requests per second per namespace](#delete-requests-per-second-per-namespace)                         | 100          | 100          | 100           | 100             |
| [Delete records per second per namespace](#delete-records-per-second-per-namespace)                           | 5,000        | 5,000        | 5,000         | 5,000           |
| [Delete records per second per index](#delete-records-per-second-per-index)                                   | 5,000        | 5,000        | 5,000         | 5,000           |
| [Delete by metadata requests per second per namespace](#delete-by-metadata-requests-per-second-per-namespace) | 5            | 5            | 5             | 5               |
| [Delete by metadata requests per second per index](#delete-by-metadata-requests-per-second-per-index)         | 500          | 500          | 500           | 500             |

#### Model throughput limits

| Metric                                                                          | Starter plan   | Builder plan   | Standard plan  | Enterprise plan |
| :------------------------------------------------------------------------------ | :------------- | :------------- | :------------- | :-------------- |
| [Embedding tokens per minute per model](#embedding-tokens-per-minute-per-model) | Model-specific | Model-specific | Model-specific | Model-specific  |
| [Rerank requests per minute per model](#rerank-requests-per-minute-per-model)   | Model-specific | Model-specific | Model-specific | Model-specific  |

### Read units per month per org

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 1,000,000    | 2,000,000    | Unlimited     | Unlimited       |

[Read units](/guides/manage-cost/understanding-cost#read-units) measure the compute, I/O, and network resources used by [fetch](/guides/manage-data/fetch-data), [query](/guides/search/search-overview), and [list](/guides/manage-data/list-record-ids) requests to serverless indexes. When you reach the monthly read unit limit for an organization, fetch, query, and list requests to serverless indexes in the organization will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached your read unit limit for the current month limit. 
  To continue reading data, upgrade your plan. 
  ```
</Accordion>

To continue reading from serverless indexes in the organization, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan).

To check how close you are to the monthly read unit limit for your organization, do the following:

1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects).
2. Select the project.
3. Select any index in the project.
4. Look under **Usage**.

<Note>
  Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide.
</Note>

### Write units per month per org

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 2,000,000    | 5,000,000    | Unlimited     | Unlimited       |

[Write units](/guides/manage-cost/understanding-cost#write-units) measure the storage and compute resources used by [upsert](/guides/index-data/upsert-data), [update](/guides/manage-data/update-data), and [delete](/guides/manage-data/delete-data) requests to serverless indexes. When you reach the monthly write unit limit for an organization, upsert, update, and delete requests to serverless indexes in the organization will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached your write unit limit for the current month. 
  To continue writing data, upgrade your plan.
  ```
</Accordion>

To continue writing data to serverless indexes in the organization, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan).

To check how close you are to the monthly write unit limit for your organization, do the following:

1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects).
2. Select the project.
3. Select any index in the project.
4. Look under **Usage**.

### Upsert size per second per namespace

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 50 MB        | 50 MB        | 50 MB         | 50 MB           |

When you reach the per second [upsert](/guides/index-data/upsert-data) size for a namespace in an index, additional upserts will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max upsert size limit per second for index <index name>. 
  Pace your upserts or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Query read units per second per index

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 2,000        | 2,000        | 2,000         | 2,000           |

Pinecone measures [query](/guides/search/search-overview) usage in [read units](/guides/manage-cost/understanding-cost#read-units). When you reach the per second limit for queries across all namespaces in an index, additional queries will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max query read units per second for index <index name>. 
  Pace your queries or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

To check how many read units a query consumes, [check the query response](/guides/manage-cost/monitor-usage-and-costs#read-units).

<Note>
  Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide.
</Note>

### Query requests per second per namespace

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 100          | 100          | 100           | 100             |

When you reach the per second [query](/guides/search/search-overview) limit for a namespace in an index, additional queries will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the query QPS limit for namespace {namespace_name} ({limit} QPS). Pace your queries,
  consider Dedicated Read Nodes for your index, or contact Pinecone Support
  (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

<Note>
  Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide.
</Note>

### Update records per second per namespace

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 100          | 100          | 100           | 100             |

When you reach the per second [update](/guides/manage-data/update-data) limit for a namespace in an index, additional updates will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max update records per second for namespace <namespace name>. 
  Pace your update requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Update requests per second per namespace

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 100          | 100          | 100           | 100             |

When you reach the per second [update](/guides/manage-data/update-data) request limit for a namespace in an index, additional update requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the update QPS limit for namespace {namespace_name} ({limit} QPS). Pace your update requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

<Tip>
  If you need to update most of the records in a large namespace, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) for help creating an export to enable a faster and more cost-effective approach.
</Tip>

### Update by metadata requests per second per namespace

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 5            | 5            | 5             | 5               |

When you reach the per second [update by metadata](/guides/manage-data/update-data#update-metadata-across-multiple-records) request limit for a namespace in an index, additional update by metadata requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max update by metadata requests per second for namespace <namespace name>. Pace your update by metadata requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Update by metadata requests per second per index

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 500          | 500          | 500           | 500             |

When you reach the per second [update by metadata](/guides/manage-data/update-data#update-metadata-across-multiple-records) request limit across all namespaces in an index, additional update by metadata requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max update by metadata requests per second for index <index name>. Pace your update by metadata requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Upsert requests per second per namespace

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 100          | 100          | 100           | 100             |

When you reach the per second [upsert](/guides/index-data/upsert-data) request limit for a namespace in an index, additional upsert requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the upsert QPS limit for namespace {namespace_name} ({limit} QPS). Pace your upsert requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Fetch requests per second per index

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 100          | 100          | 100           | 100             |

When you reach the per second [fetch](/guides/manage-data/fetch-data) limit across all namespaces in an index, additional fetch requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max fetch requests per second for index <index name>.
  Pace your fetch requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

<Note>
  Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide.
</Note>

### List requests per second per index

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 200          | 200          | 200           | 200             |

When you reach the per second [list](/guides/manage-data/list-record-ids) limit across all namespaces in an index, additional list requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max list requests per second for index <index name>.
  Pace your list requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

<Note>
  Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide.
</Note>

### Describe index stats requests per second per index

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 100          | 100          | 100           | 100             |

When you reach the per second [describe index stats](/reference/api/2024-10/data-plane/describeindexstats) limit across all namespaces in an index, additional describe index stats requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max describe_index_stats requests per second for index <index>. 
  Pace your describe_index_stats requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Delete requests per second per namespace

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 100          | 100          | 100           | 100             |

When you reach the per second [delete](/guides/manage-data/delete-data) request limit for a namespace in an index, additional delete requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the delete QPS limit for namespace {namespace_name} ({limit} QPS). Pace your delete requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Delete records per second per namespace

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 5000         | 5000         | 5000          | 5000            |

When you reach the per second [delete](/guides/manage-data/delete-data) limit for a namespace in an index, additional deletes will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max delete records per second for namespace <namespace name>. 
  Pace your delete requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Delete records per second per index

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 5000         | 5000         | 5000          | 5000            |

When you reach the per second [delete](/guides/manage-data/delete-data) limit across all namespaces in an index, additional deletes will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max delete records per second for index <index name>. 
  Pace your delete requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Delete by metadata requests per second per namespace

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 5            | 5            | 5             | 5               |

When you reach the per second [delete by metadata](/guides/manage-data/delete-data#delete-records-by-metadata) request limit for a namespace in an index, additional delete by metadata requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max delete by metadata requests per second for namespace <namespace name>. Pace your delete by metadata requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Delete by metadata requests per second per index

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 500          | 500          | 500           | 500             |

When you reach the per second [delete by metadata](/guides/manage-data/delete-data#delete-records-by-metadata) request limit across all namespaces in an index, additional delete by metadata requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max delete by metadata requests per second for index <index name>. Pace your delete by metadata requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Embedding tokens per minute per model

| Embedding model              | Input type | Starter plan | Builder plan | Standard plan | Enterprise plan |
| :--------------------------- | :--------- | :----------- | :----------- | :------------ | :-------------- |
| `llama-text-embed-v2`        | Passage    | 250,000      | 250,000      | 1,000,000     | 1,000,000       |
|                              | Query      | 50,000       | 50,000       | 250,000       | 250,000         |
| `multilingual-e5-large`      | Passage    | 250,000      | 250,000      | 1,000,000     | 1,000,000       |
|                              | Query      | 50,000       | 50,000       | 250,000       | 250,000         |
| `pinecone-sparse-english-v0` | Passage    | 250,000      | 250,000      | 3,000,000     | 3,000,000       |
|                              | Query      | 250,000      | 250,000      | 3,000,000     | 3,000,000       |

When you reach the per minute token limit for an [embedding model](/guides/index-data/create-an-index#embedding-models) hosted by Pinecone, additional embeddings will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max embedding tokens per minute (<limit>) model '<model name>'' and input type '<passage|query>' for the current project. 
  To increase this limit, upgrade your plan.
  ```
</Accordion>

To increase this limit, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). Otherwise, you can handle this limit by [implementing retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic).

### Embedding tokens per month per model

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 5,000,000    | 10,000,000   | Unlimited     | Unlimited       |

When you reach the monthly token limit for an [embedding model](/guides/index-data/create-an-index#embedding-models) hosted by Pinecone, additional embeddings will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the embedding token limit (<limit>) for model <model name> for the current month. 
  To continue using this model, upgrade your plan.
  ```
</Accordion>

To increase this limit, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan) or [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Rerank requests per minute per model

| Reranking model        | Starter plan  | Builder plan  | Standard plan | Enterprise plan |
| :--------------------- | :------------ | :------------ | :------------ | :-------------- |
| `cohere-rerank-4-fast` | Not available | Not available | 300           | 300             |
| `cohere-rerank-3.5`    | Not available | Not available | 300           | 300             |
| `bge-reranker-v2-m3`   | 60            | 60            | 60            | 60              |
| `pinecone-rerank-v0`   | 60            | Not available | 60            | 60              |

When you reach the per minute request limit for a [reranking model](/guides/search/rerank-results#reranking-models) hosted by Pinecone, additional reranking requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max rerank requests per minute (<limit>) for model '<model name>' for the current project. 
  To increase this limit, upgrade your plan.
  ```
</Accordion>

To increase this limit, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan).

### Rerank requests per month per model

| Reranking model        | Starter plan  | Builder plan  | Standard plan | Enterprise plan |
| :--------------------- | :------------ | :------------ | :------------ | :-------------- |
| `cohere-rerank-4-fast` | Not available | Not available | Unlimited     | Unlimited       |
| `cohere-rerank-3.5`    | Not available | Not available | Unlimited     | Unlimited       |
| `bge-reranker-v2-m3`   | 500           | 1,000         | Unlimited     | Unlimited       |
| `pinecone-rerank-v0`   | 500           | Not available | Unlimited     | Unlimited       |

When you reach the monthly request limit for a [reranking model](/guides/search/rerank-results#reranking-models) hosted by Pinecone, additional reranking requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the rerank request limit (<limit>) for model <model name> for the current month. 
  To continue using this model, upgrade your plan.
  ```
</Accordion>

To increase this limit, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan) or [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Inference requests per second or minute, per project

| Metric                        | Starter plan | Builder plan | Standard plan | Enterprise plan |
| :---------------------------- | :----------- | :----------- | :------------ | :-------------- |
| Inference requests per second | 100          | 100          | 100           | 100             |
| Inference requests per minute | 2000         | 2000         | 2000          | 2000            |

When you reach the per second or per minute request limit, inference requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max inference requests per second (<limit>) for the current project.
  ```
</Accordion>

<Note>
  This error indicates per second or per minute, as applicable.
</Note>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic).

## Object limits

Object limits are restrictions on the number or size of objects in Pinecone. Object limits vary based on [pricing plan](https://www.pinecone.io/pricing/).

| Metric                                                                         | Starter plan | Builder plan | Standard plan | Enterprise plan |
| :----------------------------------------------------------------------------- | :----------- | :----------- | :------------ | :-------------- |
| [Projects per organization](#projects-per-organization)                        | 1            | 5            | 20            | 100             |
| [Users per organization](#users-per-organization)                              | 2            | 5            | Unlimited     | Unlimited       |
| [Serverless indexes per project](#serverless-indexes-per-project) <sup>1</sup> | 5            | 10           | 20            | 200             |
| [Serverless index storage per org](#serverless-index-storage-per-org)          | 2 GB         | 10 GB        | N/A           | N/A             |
| [Namespaces per serverless index](#namespaces-per-serverless-index)            | 100          | 1,000        | 100,000       | 100,000         |
| [Serverless backups per project](#serverless-backups-per-project)              | N/A          | N/A          | 500           | 1000            |
| [Collections per project](#collections-per-project)                            | 100          | N/A          | N/A           | N/A             |

<sup>1 On the Starter plan, all serverless indexes must be in the `us-east-1` region of AWS. Builder, Standard, and Enterprise plans can create indexes in any [supported region](/guides/index-data/create-an-index#cloud-regions).</sup><br />

### Projects per organization

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 1            | 5            | 20            | 100             |

When you reach this quota for an organization, trying to [create projects](/guides/projects/create-a-project) will fail and return a `403 - QUOTA_EXCEEDED` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max projects allowed in organization <org name>. 
  To add more projects, upgrade your plan.
  ```
</Accordion>

To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan) or [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Users per organization

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 2            | 5            | Unlimited     | Unlimited       |

When you reach this quota for an organization, trying to add users to the organization will fail. To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan).

### Serverless indexes per project

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 5            | 10           | 20            | 200             |

When you reach this quota for a project, trying to [create serverless indexes](/guides/index-data/create-an-index#create-a-serverless-index) in the project will fail and return a `403 - QUOTA_EXCEEDED` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max serverless indexes allowed in project <project>. 
  Use namespaces to partition your data into logical groups, or upgrade your plan to add more serverless indexes.
  ```
</Accordion>

To stay under this quota, consider using [namespaces](/guides/index-data/create-an-index#namespaces) instead of creating multiple indexes. Namespaces let you partition your data into logical groups within a single index. This approach not only helps you stay within index limits, but can also improve query performance and lower costs by limiting searches to relevant data subsets.

To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan).

### Serverless index storage per org

<Note>This limit applies to organizations on the Starter and Builder plans only.</Note>

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 2 GB         | 10 GB        | N/A           | N/A             |

When you've reached this quota for an organization, updates and upserts into serverless indexes will fail and return a `403 - QUOTA_EXCEEDED` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max storage allowed for organization <org name>. 
  To update or upsert new data, delete records or upgrade your plan.
  ```
</Accordion>

To continue writing data into your serverless indexes, [delete records](/guides/manage-data/delete-data) to bring your organization under the limit or [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan).

### Namespaces per serverless index

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 100          | 1,000        | 100,000       | 100,000         |

When you reach this quota for a serverless index, trying to [upsert records into a new namespace](/guides/index-data/upsert-data) in the index will fail and return a `403 - QUOTA_EXCEEDED` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max namespaces allowed in serverless index <index name>. 
  To add more namespaces, upgrade your plan.
  ```
</Accordion>

To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan).

<Note>
  [Namespaces per serverless index](/reference/api/database-limits#namespaces-per-serverless-index) vary by plan. On the Standard and Enterprise plans, Pinecone can accommodate million-scale namespaces and beyond for specific use cases. If your application requires more than 100,000 namespaces, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).
</Note>

### Serverless backups per project

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| N/A          | N/A          | 500           | 1000            |

Backups are not available on the Starter or Builder plans. On the Standard and Enterprise plans, when you reach this quota for a project, trying to [create serverless backups](/guides/manage-data/back-up-an-index) in the project will fail and return a `403 - QUOTA_EXCEEDED` status with the following error:

<Accordion title="Error response">
  ```
  Backup failed to create. Quota for number of backups per index exceeded.
  ```
</Accordion>

### Collections per project

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 100          | N/A          | N/A           | N/A             |

When you reach this quota for a project, trying to [create collections](/guides/manage-data/back-up-an-index) in the project will fail and return a `403 - QUOTA_EXCEEDED` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max collections allowed in project <project name>. 
  To add more collections, upgrade your plan.
  ```
</Accordion>

To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan).

## Operation limits

Operation limits are restrictions on the size, number, or other characteristics of operations in Pinecone. Operation limits are fixed and do not vary based on pricing plan.

### Upsert limits

| Metric                                                             | Limit                                                         |
| :----------------------------------------------------------------- | :------------------------------------------------------------ |
| Max [batch size](/guides/index-data/upsert-data#upsert-in-batches) | 2 MB or 1000 records with vectors <br /> 96 records with text |
| Max documents per upsert request                                   | 1000                                                          |
| Max document upsert request size                                   | 2 MB                                                          |
| Max document size                                                  | 2 MB                                                          |
| Max `full_text_search` string fields per schema                    | 100                                                           |
| Max size per `full_text_search` string field                       | 100 KB                                                        |
| Max tokens per `full_text_search` string field                     | 10,000                                                        |
| Max bytes per token                                                | 256 bytes                                                     |
| Max filterable metadata size per document                          | 40 KB                                                         |
| Max length for a record ID                                         | 512 characters                                                |
| Max dimensionality for dense vectors                               | 20,000                                                        |
| Max non-zero values for sparse vectors                             | 2048                                                          |
| Max dimensionality for sparse vectors                              | 4.2 billion                                                   |

The 40 KB filterable metadata limit does not apply to `full_text_search` text fields.

### Import limits

<Note>
  If your import exceeds these limits, you'll get an error specifying the limit exceeded. See [Troubleshooting](/guides/index-data/import-data#troubleshooting) for details.
</Note>

| Metric                                        | Limit     |
| :-------------------------------------------- | :-------- |
| Max namespaces per import                     | 10,000    |
| Max total input data size (on-demand indexes) | 1 TB      |
| Max total input data size (DRN indexes)       | Unlimited |
| Max files per import                          | 100,000   |
| Max size per file                             | 10 GB     |

The total input data size limit does not apply to indexes with [dedicated read nodes](/guides/index-data/dedicated-read-nodes).

Bulk import supports indexes without a schema definition (Parquet files) and indexes with document schemas ([JSONL files](/guides/search/full-text-search#bulk-import)). Semantic-text (auto-embedded) fields are not yet supported in document schemas.

### Query limits

| Metric            | Limit  |
| :---------------- | :----- |
| Max `top_k` value | 10,000 |
| Max result size   | 4MB    |

The query result size is affected by the dimension of the dense vectors and whether or not dense vector values and metadata are included in the result.

<Tip>
  If a query fails due to exceeding the 4MB result size limit, choose a lower `top_k` value, or use `include_metadata=False` or `include_values=False` to exclude metadata or values from the result. For better performance, especially with higher `top_k` values, avoid including vector values unless you need them.
</Tip>

### Fetch limits

**Fetch by ID limits:**

| Metric                           | Limit |
| :------------------------------- | :---- |
| Max record IDs per fetch request | 1,000 |

**Fetch by metadata limits:**

| Metric                   | Limit                               |
| :----------------------- | :---------------------------------- |
| Max records per response | 10,000                              |
| Max response size        | 4 MB                                |
| Max request rate         | 5 requests per second per namespace |

To retrieve more than 10,000 matching records, paginate through results using the `paginationToken` parameter. See [Fetch records by metadata](/guides/manage-data/fetch-data#fetch-records-by-metadata).

### Delete limits

| Metric                            | Limit |
| :-------------------------------- | :---- |
| Max record IDs per delete request | 1,000 |

### Metadata filter limits

The following limits apply to [metadata filter expressions](/guides/search/filter-by-metadata#metadata-filter-expressions) used in query, delete, update, and fetch operations.

| Limit                                       | Value  | Description                                                                                                                                                                                                      |
| :------------------------------------------ | :----- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Maximum values per `$in` or `$nin` operator | 10,000 | Each `$in` or `$nin` operator accepts up to 10,000 values in its array. This limit applies per operator—if you have multiple `$in` operators in a single filter, each is independently limited to 10,000 values. |

When you exceed this limit, the request will fail and return a `400 - BAD_REQUEST` error.

#### Rationale

Large `$in` operators can impact query performance and cost. Filters with thousands of values increase request payload size and end-to-end latency. Additionally, using large filters typically indicates a shared namespace architecture, which increases query costs—queries scan the entire namespace regardless of filters.

#### Alternative approaches

If you need to filter by more than 10,000 values, consider these alternatives:

* **Use namespaces for tenant isolation**: Instead of filtering by tenant IDs within a single namespace, create separate namespaces for each tenant or tenant group. This can also reduce query costs. See [Design for multi-tenancy](/guides/index-data/data-modeling#design-for-multi-tenancy).
* **Use broader access control groups**: Instead of filtering by individual user IDs, filter by organization, project, or role. This reduces the number of values in your `$in` filter. See [Design for multi-tenancy](/guides/index-data/data-modeling#use-access-control-groups-instead-of-individual-ids).
* **Post-filter client-side**: Retrieve a larger top K without filtering (for example, top 1000), then filter results client-side.
* **Run multiple queries**: Split your filter into multiple queries with smaller `$in` operators and combine the results client-side.

<Tip>
  To avoid hitting this limit in production, validate the size of your `$in` and `$nin` arrays in your application code before making the request to Pinecone.
</Tip>

## Identifier limits

An identifier is a string of characters used to identify "named" [objects in Pinecone](/guides/get-started/concepts). The following Pinecone objects use strings as identifiers:

| Object                                                    | Field       | Max # characters | Allowed characters                                                                                                                        |
| --------------------------------------------------------- | ----------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| [Organization](/guides/get-started/concepts#organization) | `name`      | 512              | <ul><li>UTF-8 except `\0`</li><li>Cannot be empty</li></ul>                                                                               |
| [Project](/guides/get-started/concepts#project)           | `name`      | 512              | <ul><li>UTF-8 except `\0`</li><li>Cannot be empty</li></ul>                                                                               |
| [Index](/guides/get-started/concepts#index)               | `name`      | 45               | <ul><li>`a-z`, `0-9`, and `-`</li><li>Must be lowercase</li><li>Cannot start or end with `-`</li><li>Cannot be empty</li></ul>            |
| [Namespace](/guides/get-started/concepts#namespace)       | `namespace` | 512              | <ul><li>ASCII except `\0`</li><li>For the default namespace, use `""` (or `"__default__"`, in API versions `2025-04` and later)</li></ul> |
| [Record](/guides/get-started/concepts#record)             | `id`        | 512              | <ul><li>ASCII except `\0`</li><li>Cannot be empty</li></ul>                                                                               |


# Errors
Source: https://docs.pinecone.io/reference/api/errors

Pinecone REST API: Pinecone uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the range.

Pinecone uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the `2xx` range indicate success, codes in the `4xx` range indicate an error that failed given the information provided, and codes in the `5xx` range indicate an error with Pinecone's servers.

For guidance on handling errors in production, see [Error handling](/guides/production/error-handling).

## 200 - OK

The request succeeded.

## 201 - CREATED

The request succeeded and a new resource was created.

## 202 - NO CONTENT

The request succeeded, but there is no content to return.

## 400 - INVALID ARGUMENT

The request failed due to an invalid argument.

## 401 - UNAUTHENTICATED

The request failed due to a missing or invalid [API key](/guides/projects/understanding-projects#api-keys).

## 402 - PAYMENT REQUIRED

The request failed due to delinquent payment or account deactivation for non-payment. See [Account deactivation for non-payment](/guides/organizations/manage-billing/non-payment-account-deactivation).

## 403 - FORBIDDEN

The request failed due to an exceeded [quota](/reference/api/database-limits#object-limits) or [index deletion protection](/guides/manage-data/manage-indexes#configure-deletion-protection).

## 404 - NOT FOUND

The request failed because the resource was not found.

## 409 - ALREADY EXISTS

The request failed because the resource already exists.

## 412 - FAILED PRECONDITIONS

The request failed due to preconditions not being met. |

## 422 - UNPROCESSABLE ENTITY

The request failed because the server was unable to process the contained instructions.

## 429 - TOO MANY REQUESTS

The request was [rate-limited](/reference/api/database-limits#rate-limits). [Implement retry logic with exponential backoff](/guides/production/error-handling#handle-rate-limits-429) to handle this error.

## 500 - UNKNOWN

An internal server error occurred. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) to handle transient errors.

## 502 - BAD GATEWAY

The API gateway received an invalid response from a backend service. This is typically a temporary error. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) to handle transient errors.

## 503 - UNAVAILABLE

The server is currently unavailable. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) to handle transient errors.

## 504 - GATEWAY TIMEOUT

The API gateway did not receive a timely response from the backend server. This can occur due to slow requests or backend processing delays. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) to handle transient errors.


# API reference
Source: https://docs.pinecone.io/reference/api/introduction

Pinecone API reference overview for Database, Inference, and Admin endpoints with supported SDKs including Python, Node.js, Java, and Go.

Pinecone's APIs let you interact programmatically with your Pinecone account.

<Note>
  [SDK versions](/reference/pinecone-sdks#sdk-versions) are pinned to specific API versions.
</Note>

## Database

Use the Database API to store and query records in [Pinecone Database](/guides/get-started/quickstart).

The following Pinecone SDKs support the Database API:

<CardGroup>
  <Card title="CLI" icon="terminal" href="/reference/cli/overview" />

  <Card title="Python SDK" icon="python" href="/reference/sdks/python/overview" />

  <Card title="Node.js SDK" icon="node-js" href="/reference/sdks/node/overview" />

  <Card title="Java SDK" icon="java" href="/reference/sdks/java/overview" />

  <Card title="Go SDK" icon="golang" href="/reference/sdks/go/overview" />
</CardGroup>

## Inference

Use the Inference API to generate vector embeddings and rerank results using [embedding models](/guides/index-data/create-an-index#embedding-models) and [reranking models](/guides/search/rerank-results#reranking-models) hosted on Pinecone's infrastructure.

There are two ways to use the Inference API:

* As a standalone service, through the [Rerank documents](/reference/api/latest/inference/rerank) and [Generate vectors](/reference/api/latest/inference/generate-embeddings) endpoints.
* As an integrated part of database operations, through the [Create an index with integrated embedding](/reference/api/latest/control-plane/create_for_model), [Upsert text](/reference/api/latest/data-plane/upsert_records), and [Search with text](/reference/api/latest/data-plane/search_records) endpoints.

The following Pinecone SDKs support using the Inference API:

<CardGroup>
  <Card title="Python SDK" icon="python" href="/reference/sdks/python/overview" />

  <Card title="Node.js SDK" icon="node-js" href="/reference/sdks/node/overview" />

  <Card title="Java SDK" icon="java" href="/reference/sdks/java/overview" />

  <Card title="Go SDK" icon="golang" href="/reference/sdks/go/overview" />
</CardGroup>


# Known limitations
Source: https://docs.pinecone.io/reference/api/known-limitations

Known limitations and feature restrictions for Pinecone indexes, including upsert consistency, metadata rules, and serverless caveats.

This page describes known limitations and feature restrictions in Pinecone.

## General

* [Upserts](/guides/index-data/upsert-data)
  * Pinecone is eventually consistent, so there can be a slight delay before upserted records are available to query.

    After upserting records, use the [`describe_index_stats`](/reference/api/2024-10/data-plane/describeindexstats) operation to check if the current vector count matches the number of records you expect, although this method may not work for pod-based indexes with multiple replicas.
  * Only indexes using the [dotproduct distance metric](/guides/index-data/indexing-overview#dotproduct) support querying sparse-dense vectors.

    Upserting, updating, and fetching sparse-dense vectors in indexes with a different distance metric will succeed, but querying will return an error.
  * Indexes created before February 22, 2023 do not support sparse vectors.
* [Metadata](/guides/index-data/upsert-data#upsert-with-metadata-filters)
  * Null metadata values aren't supported. Instead of setting a key to `null`, remove the key from the metadata payload.
  * Nested JSON objects are not supported.

## Serverless indexes

Serverless indexes do not support the following features:

* [Filtering index statistics by metadata](/reference/api/2024-10/data-plane/describeindexstats)
* [Private endpoints](/guides/production/configure-private-endpoints)

  * This feature is available on AWS only.


# API versioning
Source: https://docs.pinecone.io/reference/api/versioning

Pinecone REST API: Pinecone's APIs are versioned to ensure that your applications continue to work as expected as the platform evolves.

Pinecone's APIs are versioned to ensure that your applications continue to work as expected as the platform evolves. Versions are named by release date in the format `YYYY-MM`, for example, `2025-10`.

## Release schedule

On a quarterly basis, Pinecone releases a new **stable** API version as well as a **release candidate** of the next stable version.

* **Stable:** Each stable version remains unchanged and supported for a minimum of 12 months. Since stable versions are released every 3 months, this means you have at least 9 months to test and migrate your app to the newest stable version before support for the previous version is removed.

* **Release candidate:** The release candidate gives you insight into the upcoming changes in the next stable version. It is available for approximately 3 months before the release of the stable version and can include new features, improvements, and [breaking changes](#breaking-changes).

Below is an example of Pinecone's release schedule:

<img />

<img />

## Specify an API version

<Warning>
  When using the API directly, it is important to specify an API version in your requests. If you don't, requests default to the oldest supported stable version. Once support for that version ends, your requests will default to the next oldest stable version, which could include breaking changes that require you to update your integration.
</Warning>

To specify an API version, set the `X-Pinecone-Api-Version` header to the version name.

For example, to use the latest stable version (`2026-04`) to describe an index, set the `X-Pinecone-Api-Version` header:

```shell curl theme={null}
PINECONE_API_KEY="YOUR_API_KEY"

curl -i -X GET "https://api.pinecone.io/indexes/movie-recommendations" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2026-04"
```

To use an older version, specify that version instead.

## SDK versions

Official [Pinecone SDKs](/reference/pinecone-sdks) provide convenient access to Pinecone APIs. SDK versions are pinned to specific API versions. When a new API version is released, a new version of the SDK is also released.

For the mapping between SDK and API versions, see [SDK versions](/reference/pinecone-sdks#sdk-versions).

## Breaking changes

Breaking changes are changes that can potentially break your integration with a Pinecone API. Breaking changes include:

* Removing an entire operation
* Removing or renaming a parameter
* Removing or renaming a response field
* Adding a new required parameter
* Making a previously optional parameter required
* Changing the type of a parameter or response field
* Removing enum values
* Adding a new validation rule to an existing parameter
* Changing authentication or authorization requirements

## Non-breaking changes

Non-breaking changes are additive and should not break your integration. Additive changes include:

* Adding an operation
* Adding an optional parameter
* Adding an optional request header
* Adding a response field
* Adding a response header
* Adding enum values

## Get updates

To ensure you always know about upcoming API changes, follow the [Release notes](/release-notes/).


# CLI authentication
Source: https://docs.pinecone.io/reference/cli/authentication

Authenticate the Pinecone CLI using user login, service accounts, or API keys, including auth priority and Admin API access rules.

This document describes how to authenticate the Pinecone CLI to manage your Pinecone resources.

## Authentication methods

| Method                              | Admin API | Control/data plane | Best for                         |
| ----------------------------------- | --------- | ------------------ | -------------------------------- |
| [User login](#user-login)           | ✅         | ✅                  | Interactive use                  |
| [Service account](#service-account) | ✅         | ✅                  | Automation with Admin API access |
| [API key](#api-key)                 | ❌         | ✅                  | Simple automation, CI/CD         |

### User login

Authenticate through a web browser. The token refreshes automatically and stays valid for up to 120 days (re-auth required after 30 days of inactivity).

```bash theme={null}
pc auth login
```

The CLI auto-targets your default organization and its first project. Change with `pc target -o "my-org" -p "my-project"`.

### Service account

Authenticate with credentials from a [service account](/guides/organizations/manage-service-accounts).

```bash theme={null}
pc auth configure --client-id "ID" --client-secret "SECRET"

# Or via environment variables
export PINECONE_CLIENT_ID="your-client-id"
export PINECONE_CLIENT_SECRET="your-client-secret"
```

The CLI auto-targets the service account's organization. For projects: auto-selects if one exists, prompts if multiple exist, or set manually with `pc target -p "my-project"`.

### API key

Authenticate with an [API key](/guides/projects/manage-api-keys). API keys can't access the Admin API.

```bash theme={null}
pc auth configure --api-key "YOUR_API_KEY"

# Or via environment variable
export PINECONE_API_KEY="your-api-key"
```

<Warning>
  API keys are scoped to a specific project. When set, control/data plane operations use the **key's project**, ignoring any [target context](/reference/cli/target-context) you've set.
</Warning>

## Auth priority

When multiple credentials exist, the CLI chooses based on operation type. Within each credential type, environment variables take precedence over stored configuration.

**Control/data plane operations:**

1. API key
2. User login token (via [managed keys](#managed-keys))
3. Service account (via [managed keys](#managed-keys))

**Admin API operations:**

1. User login token
2. Service account

<Note>
  User login and service account are mutually exclusive when configured via CLI commands—each clears the other. However, service account env vars don't clear a stored user login token.
</Note>

**Example scenarios:**

* If `PINECONE_API_KEY` is set, the CLI uses it for control/data plane operations, regardless of any stored API key.
* If you're logged in via `pc auth login` and also have `PINECONE_CLIENT_ID`/`PINECONE_CLIENT_SECRET` set, the user login token is used for everything—the service account env vars are ignored.
* If you have an API key configured and are also logged in, the API key is used for control/data plane operations, but user login is used for Admin API operations (since API keys can't access Admin API).

## Managed keys

When using user login or service account (without a default API key), the CLI automatically creates and manages API keys for control/data plane operations. This happens transparently on first use.

* **Stored locally:** `~/.config/pinecone/secrets.yaml` (permissions 0600)
* **Stored remotely:** Visible in console as `pinecone-cli-{id}` with origin `cli_created`

```bash theme={null}
# List locally tracked managed keys
pc auth local-keys list

# Delete managed keys (local + remote)
pc auth local-keys prune

# Delete only CLI-created managed keys
pc auth local-keys prune --origin cli

# Delete only user-created managed keys
pc auth local-keys prune --origin user

# Delete a specific API key by ID
pc api-key delete --id "KEY_ID"
```

<Note>
  When you run `pc api-key create --store` for a project that already has a CLI-created managed key, the CLI automatically deletes the old remote key before storing the new one.
</Note>

## Logging out

```bash theme={null}
pc auth logout
```

Clears all local auth data: tokens, credentials, API keys, managed keys, and [target context](/reference/cli/target-context).

<Note>
  `pc auth logout` doesn't delete managed keys from Pinecone's servers. Run `pc auth local-keys prune` first for full cleanup.
</Note>

## Local storage

Auth data is stored in `~/.config/pinecone/` with 0600 permissions:

| File           | Contents                                                         |
| -------------- | ---------------------------------------------------------------- |
| `secrets.yaml` | OAuth token, service account credentials, API keys, managed keys |
| `state.yaml`   | Target org/project                                               |
| `config.yaml`  | CLI settings (color, environment)                                |

## Check status

```bash theme={null}
pc auth status
```

Shows your current authentication method, target organization and project, token expiration (for user login), and environment configuration.


# CLI command reference
Source: https://docs.pinecone.io/reference/cli/command-reference

Complete Pinecone CLI command reference covering syntax, subcommands, flags, help output, and exit codes for auth, index, and project.

This document provides a complete reference for all Pinecone CLI commands.

## Command structure

The Pinecone CLI uses a hierarchical command structure. Each command consists of a primary command followed by one or more subcommands and optional flags.

```bash theme={null}
pc <command> <subcommand> [flags]
pc <command> <subcommand> <subcommand> [flags]
```

For example:

```bash theme={null}
# Top-level command with flags
pc target -o "organization-name" -p "project-name"

# Command (index) and subcommand (list)
pc index list

# Command (index) and subcommand (create) with flags
pc index create \
  --name my-index \
  --dimension 1536 \
  --metric cosine \
  --cloud aws \
  --region us-east-1

# Command (auth) and nested subcommands (local-keys prune) with flags
pc auth local-keys prune --id proj-abc123 --skip-confirmation
```

## Getting help

The CLI provides help for commands at every level:

```bash theme={null}
# top-level help
pc --help
pc -h

# command help
pc auth --help
pc index --help
pc project --help

# subcommmand help
pc index create --help
pc project create --help
pc auth configure --help

# nested subcommand help
pc auth local-keys prune --help
```

## Exit codes

All commands return exit code `0` for success and `1` for error.

## Available commands

This section describes all commands offered by the Pinecone CLI.

### Top-level commands

<AccordionGroup>
  <Accordion title="pc login (Authenticate via user login)">
    **Description**

    Authenticate via a web browser. After login, set a [target org and project](/reference/cli/target-context) with `pc target` before accessing data. This command defaults to an initial organization and project to which
    you have access (these values display in the terminal), but you can change them with `pc target`.

    **Usage**

    ```bash theme={null}
    pc login
    ```

    **Flags**

    None

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Log in via browser
    pc login

    # Then set target context
    pc target -o "my-org" -p "my-project"
    ```

    <Note>
      This is an alias for `pc auth login`. Both commands perform the same operation.
    </Note>
  </Accordion>

  <Accordion title="pc logout (Clear credentials / log out)">
    **Description**

    Clears all authentication data from local storage, including:

    * User login token
    * Service account credentials (client ID and secret)
    * Default (manually specified) API key
    * Locally managed keys (for all projects)
    * Target organization and project context

    **Usage**

    ```bash theme={null}
    pc logout
    ```

    **Flags**

    None

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Clear all credentials and context
    pc logout
    ```

    <Note>
      This is an alias for `pc auth logout`. Both commands perform the same operation. Does not delete managed API keys from Pinecone's servers. Run `pc auth local-keys prune` before logging out to fully clean up.
    </Note>
  </Accordion>

  <Accordion title="pc target (Set target organization and project)">
    **Description**

    Set the target organization and project for the CLI. Supports interactive organization and project selection or direct specification via flags.  For details, see [CLI target context](/reference/cli/target-context).

    **Usage**

    ```bash theme={null}
    pc target [flags]
    ```

    **Flags**

    | Long flag           | Short flag | Description                    |
    | :------------------ | :--------- | :----------------------------- |
    | `--clear`           |            | Clear target context           |
    | `--json`            | `-j`       | Output in JSON format          |
    | `--org`             | `-o`       | Organization name              |
    | `--organization-id` |            | Organization ID                |
    | `--project`         | `-p`       | Project name                   |
    | `--project-id`      |            | Project ID                     |
    | `--show`            | `-s`       | Display current target context |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Interactive targeting after login
    pc login
    pc target

    # Set specific organization and project
    pc target -o "my-org" -p "my-project"

    # Show current context
    pc target --show

    # Clear all context
    pc target --clear
    ```
  </Accordion>

  <Accordion title="pc version (Show CLI version)">
    **Description**

    Displays version information for the CLI, including the version number, commit SHA, and build date.

    **Usage**

    ```bash theme={null}
    pc version
    ```

    **Flags**

    None

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Display version information
    pc version
    ```
  </Accordion>

  <Accordion title="pc whoami (Show current user)">
    **Description**

    Displays information about the currently authenticated user. To use this command, you must be authenticated via user login.

    **Usage**

    ```bash theme={null}
    pc whoami
    ```

    **Flags**

    None

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    pc whoami
    ```

    <Note>
      This is an alias for `pc auth whoami`. Both commands perform the same operation.
    </Note>
  </Accordion>
</AccordionGroup>

### Authentication

<AccordionGroup>
  <Accordion title="pc auth clear (Clear specific credentials)">
    **Description**

    Selectively clears specific authentication data without affecting other credentials. At least one flag is required.

    **Usage**

    ```bash theme={null}
    pc auth clear [flags]
    ```

    **Flags**

    | Long flag           | Short flag | Description                                         |
    | :------------------ | :--------- | :-------------------------------------------------- |
    | `--api-key`         |            | Clear only the default (manually specified) API key |
    | `--service-account` |            | Clear only service account credentials              |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Clear only the default (manually specified) API key
    pc auth clear --api-key
    pc auth status

    # Clear service account
    pc auth clear --service-account
    ```

    <Note>
      More surgical than `pc auth logout`. Does not clear user login token or managed keys. For those, use `pc auth logout` or `pc auth local-keys prune`.
    </Note>
  </Accordion>

  <Accordion title="pc auth configure (Configure service account or API key)">
    **Description**

    Configures service account credentials or a default (manually specified) API key.

    Service accounts automatically target the organization and prompt for project selection, unless there is only one project. A default API key overrides any previously specified target organization/project context. When setting a service account, this operation clears the user login token, if one exists.
    For details, see [CLI target context](/reference/cli/target-context).

    **Usage**

    ```bash theme={null}
    pc auth configure [flags]
    ```

    **Flags**

    | Long flag               | Short flag | Description                                          |
    | :---------------------- | :--------- | :--------------------------------------------------- |
    | `--api-key`             |            | Default API key to use for authentication            |
    | `--client-id`           |            | Service account client ID                            |
    | `--client-secret`       |            | Service account client secret                        |
    | `--client-secret-stdin` |            | Read client secret from stdin                        |
    | `--json`                | `-j`       | Output in JSON format                                |
    | `--project-id`          | `-p`       | Target project ID (optional, interactive if omitted) |
    | `--prompt-if-missing`   |            | Prompt for missing credentials                       |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Service account setup (auto-targets org and prompts for project)
    pc auth configure --client-id my-id --client-secret my-secret

    # Service account with specific project
    pc auth configure \
      --client-id my-id \
      --client-secret my-secret \
      -p proj-123

    # Default API key (overrides any target context)
    pc auth configure --api-key pcsk_abc123
    ```

    <Note>
      `pc auth configure --api-key "YOUR_API_KEY"` does the same thing as `pc config set-api-key "YOUR_API_KEY"`. To learn about targeting a project after authenticating with a service account, see [CLI target context](/reference/cli/target-context).
    </Note>
  </Accordion>

  <Accordion title="pc auth local-keys list (List managed keys)">
    **Description**

    Displays all [managed API keys](/reference/cli/authentication#managed-keys) stored locally by the CLI, with various details.

    **Usage**

    ```bash theme={null}
    pc auth local-keys list [flags]
    ```

    **Flags**

    | Long flag  | Short flag | Description                                |
    | :--------- | :--------- | :----------------------------------------- |
    | `--json`   | `-j`       | Output in JSON format                      |
    | `--reveal` |            | Show the actual API key values (sensitive) |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # List all locally managed keys
    pc auth local-keys list

    # Show key values
    pc auth local-keys list --reveal

    # After storing a key
    pc api-key create -n "my-key" --store
    pc auth local-keys list
    ```
  </Accordion>

  <Accordion title="pc auth local-keys prune (Delete managed keys)">
    **Description**

    Deletes locally stored [managed API keys](/reference/cli/authentication#managed-keys) from local storage and Pinecone's servers. Filters by origin (`cli`/`user`/`all`) or project ID.

    **Usage**

    ```bash theme={null}
    pc auth local-keys prune [flags]
    ```

    **Flags**

    | Long flag             | Short flag | Description                                                 |
    | :-------------------- | :--------- | :---------------------------------------------------------- |
    | `--dry-run`           |            | Preview deletions without applying                          |
    | `--id`                |            | Prune keys for specific project ID only                     |
    | `--json`              | `-j`       | Output in JSON format                                       |
    | `--origin`            | `-o`       | Filter by origin - `cli`, `user`, or `all` (default: `all`) |
    | `--skip-confirmation` |            | Skip confirmation prompt                                    |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Preview deletions
    pc auth local-keys prune --dry-run

    # Delete CLI-created keys only
    pc auth local-keys prune -o cli --skip-confirmation

    # Delete for specific project
    pc auth local-keys prune --id proj-abc123

    # Before/after check
    pc auth local-keys list
    pc auth local-keys prune -o cli
    pc auth local-keys list
    ```

    <Note>
      This deletes keys from both local storage and Pinecone servers. Use `--dry-run` to preview before committing.
    </Note>
  </Accordion>

  <Accordion title="pc auth login (Authenticate via user login)">
    **Description**

    Authenticate via user login in the web browser. After login, [set a target org and project](/reference/cli/target-context).

    **Usage**

    ```bash theme={null}
    pc auth login
    pc login  # shorthand
    ```

    **Flags**

    None

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Login and set target
    pc auth login
    pc target -o "my-org" -p "my-project"
    pc index list
    ```

    <Note>
      Tokens refresh automatically and remain valid for up to 120 days. If you're inactive for more than 30 days, you must re-authenticate. Logging in clears any existing service account credentials. This command does the same thing as `pc login`.
    </Note>
  </Accordion>

  <Accordion title="pc auth logout (Clear authentication credentials)">
    **Description**

    Clears all authentication data from local storage, including:

    * User login token
    * Service account credentials (client ID and secret)
    * Default (manually specified) API key
    * Locally managed keys (for all projects)
    * Target organization and project context

    **Usage**

    ```bash theme={null}
    pc auth logout
    ```

    **Flags**

    None

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Clear all credentials and context
    pc auth logout
    ```

    <Note>
      This command does the same thing as `pc logout`. Does not delete managed API keys from Pinecone's servers. Run `pc auth local-keys prune` before logging out to fully clean up.
    </Note>
  </Accordion>

  <Accordion title="pc auth status (Show authentication status)">
    **Description**

    Shows details about all configured authentication methods.

    **Usage**

    ```bash theme={null}
    pc auth status [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description           |
    | :-------- | :--------- | :-------------------- |
    | `--json`  | `-j`       | Output in JSON format |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Check status after login
    pc auth login
    pc auth status

    # JSON output for scripting
    pc auth status --json
    ```
  </Accordion>

  <Accordion title="pc auth whoami (Show current user information)">
    **Description**

    Displays information about the currently authenticated user. To use this command, you must be authenticated via user login.

    **Usage**

    ```bash theme={null}
    pc auth whoami
    ```

    **Flags**

    None

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    pc auth whoami
    ```

    <Note>
      This command does the same thing as `pc whoami`.
    </Note>
  </Accordion>
</AccordionGroup>

### Indexes

<AccordionGroup>
  <Accordion title="pc index configure (Update index configuration)">
    **Description**

    Modifies the configuration of an existing index.

    **Usage**

    ```bash theme={null}
    pc index configure [flags]
    ```

    **Flags**

    | Long flag                | Short flag | Description                                                     |
    | :----------------------- | :--------- | :-------------------------------------------------------------- |
    | `--index-name`           | `-i`       | Name of index to configure (required)                           |
    | `--deletion-protection`  |            | Enable or disable deletion protection - `enabled` or `disabled` |
    | `--tags`                 |            | Custom user tags (key=value pairs)                              |
    | `--json`                 | `-j`       | Output in JSON format                                           |
    | **Dedicated read nodes** |            |                                                                 |
    | `--read-mode`            |            | Read capacity mode - `ondemand` or `dedicated`                  |
    | `--read-node-type`       |            | Node type for dedicated read - `b1` or `t1`                     |
    | `--read-shards`          |            | Number of shards for dedicated read capacity                    |
    | `--read-replicas`        |            | Number of replicas for dedicated read capacity                  |
    | **Integrated embedding** |            |                                                                 |
    | `--model`                |            | Embedding model name                                            |
    | `--field-map`            |            | Field mapping for embedding (key=value pairs)                   |
    | `--read-parameters`      |            | Read parameters for embedding model (key=value pairs)           |
    | `--write-parameters`     |            | Write parameters for embedding model (key=value pairs)          |
    | **Pods**                 |            |                                                                 |
    | `--pod-type`             | `-t`       | Type of pod to use; can only upgrade when configuring           |
    | `--replicas`             | `-r`       | Number of replicas of the index to configure                    |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Enable deletion protection
    pc index configure --index-name my-index --deletion-protection enabled

    # Add tags
    pc index configure --index-name my-index --tags environment=production,team=ml

    # Switch to dedicated read capacity
    pc index configure --index-name my-index \
      --read-mode dedicated \
      --read-node-type b1 \
      --read-shards 2 \
      --read-replicas 2

    # Verify changes
    pc index describe --index-name my-index
    ```

    <Note>
      Configuration changes may take some time to take effect.
    </Note>
  </Accordion>

  <Accordion title="pc index create (Create a new index)">
    **Description**

    Creates a new index in your Pinecone project. Supports serverless, pod-based, integrated (with embedding model), and BYOC (Bring Your Own Cloud) index types.

    **Usage**

    ```bash theme={null}
    pc index create [flags]
    ```

    **Flags**

    | Long flag                | Short flag | Description                                                                    |
    | :----------------------- | :--------- | :----------------------------------------------------------------------------- |
    | `--name`                 | `-n`       | Index name (required)                                                          |
    | `--dimension`            | `-d`       | Vector dimension (required for standard indexes, optional for integrated)      |
    | `--metric`               | `-m`       | Similarity metric - `cosine`, `euclidean`, or `dotproduct` (default: `cosine`) |
    | `--cloud`                | `-c`       | Cloud provider - `aws`, `gcp`, or `azure`                                      |
    | `--region`               | `-r`       | Cloud region                                                                   |
    | `--vector-type`          | `-v`       | Vector type - `dense` or `sparse` (serverless only)                            |
    | `--source-collection`    |            | Name of the source collection from which to create the index                   |
    | `--schema`               |            | Metadata schema to control which fields are indexed (comma-separated)          |
    | `--deletion-protection`  |            | Deletion protection - `enabled` or `disabled`                                  |
    | `--tags`                 |            | Custom user tags (key=value pairs)                                             |
    | `--json`                 | `-j`       | Output in JSON format                                                          |
    | **Integrated indexes**   |            |                                                                                |
    | `--model`                |            | Integrated embedding model name                                                |
    | `--field-map`            |            | Field mapping for integrated embedding (key=value pairs)                       |
    | `--read-parameters`      |            | Read parameters for embedding model (key=value pairs)                          |
    | `--write-parameters`     |            | Write parameters for embedding model (key=value pairs)                         |
    | **BYOC indexes**         |            |                                                                                |
    | `--byoc-environment`     |            | BYOC environment to use for the index                                          |
    | **Dedicated read nodes** |            |                                                                                |
    | `--read-mode`            |            | Read capacity mode - `ondemand` or `dedicated` (default: `ondemand`)           |
    | `--read-node-type`       |            | Node type for dedicated read - `b1` or `t1`                                    |
    | `--read-shards`          |            | Number of shards (each shard provides 250 GB storage)                          |
    | `--read-replicas`        |            | Number of replicas for higher throughput                                       |
    | **Pod-based indexes**    |            |                                                                                |
    | `--environment`          |            | Environment of the index to create (for example, `us-east-1-aws`)              |
    | `--pod-type`             |            | Type of pod to use (for example, `p1.x1`, `s1.x2`)                             |
    | `--shards`               |            | Number of shards (default: `1`)                                                |
    | `--replicas`             |            | Number of replicas (default: `1`)                                              |
    | `--metadata-config`      |            | Comma-separated list of metadata fields to index for search                    |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Create serverless index
    pc index create -n my-index -d 1536 -m cosine -c aws -r us-east-1

    # Create sparse vector index
    pc index create -n sparse-index -m dotproduct -c aws -r us-east-1 --vector-type sparse

    # With integrated embedding model
    pc index create \
      -n my-index \
      -m cosine \
      -c aws \
      -r us-east-1 \
      --model multilingual-e5-large \
      --field-map text=chunk_text

    # With dedicated read capacity
    pc index create \
      -n my-index \
      -d 1536 \
      -m cosine \
      -c aws \
      -r us-east-1 \
      --read-mode dedicated \
      --read-node-type b1 \
      --read-shards 2 \
      --read-replicas 2

    # With deletion protection
    pc index create \
      -n my-index \
      -d 1536 \
      -m cosine \
      -c aws \
      -r us-west-2 \
      --deletion-protection enabled

    # From collection
    pc index create \
      -n my-index \
      -d 1536 \
      -m cosine \
      -c aws \
      -r eu-west-1 \
      --source-collection my-collection

    # Create pod-based index
    pc index create \
      -n my-index \
      -d 1536 \
      -m cosine \
      --environment us-east-1-aws \
      --pod-type p1.x1 \
      --shards 1 \
      --replicas 1
    ```

    <Note>
      For a list of valid regions for a serverless index, see [Create a serverless index](/guides/index-data/create-an-index).
    </Note>
  </Accordion>

  <Accordion title="pc index delete (Delete an index)">
    **Description**

    Permanently deletes an index and all its data. This operation cannot be undone.

    **Usage**

    ```bash theme={null}
    pc index delete [flags]
    ```

    **Flags**

    | Long flag             | Short flag | Description                                                |
    | :-------------------- | :--------- | :--------------------------------------------------------- |
    | `--index-name`        | `-i`       | Name of index to delete (required)                         |
    | `--skip-confirmation` |            | Skip the deletion confirmation prompt                      |
    | `--json`              | `-j`       | Output in JSON format (also skips the confirmation prompt) |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Delete an index (prompts for confirmation)
    pc index delete --index-name my-index

    # Skip the confirmation prompt
    pc index delete --index-name my-index --skip-confirmation

    # List before and after
    pc index list
    pc index delete --index-name test-index --skip-confirmation
    pc index list
    ```

    <Note>
      This command prompts for confirmation before deleting. Pass `--skip-confirmation` (or `--json`) to bypass the prompt in non-interactive contexts.
    </Note>
  </Accordion>

  <Accordion title="pc index describe (Show index details)">
    **Description**

    Displays detailed configuration and status information for a specific index.

    **Usage**

    ```bash theme={null}
    pc index describe [flags]
    ```

    **Flags**

    | Long flag      | Short flag | Description           |
    | :------------- | :--------- | :-------------------- |
    | `--index-name` | `-i`       | Index name (required) |
    | `--json`       | `-j`       | Output in JSON format |

    The `--name`/`-n` flag is a deprecated alias for `--index-name`/`-i`.

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Describe an index
    pc index describe -i my-index

    # JSON output
    pc index describe -i my-index -j

    # Check newly created index
    pc index create -n test-index -d 1536 -m cosine -c aws -r us-east-1
    pc index describe -i test-index
    ```
  </Accordion>

  <Accordion title="pc index stats (Show index statistics)">
    **Description**

    Displays statistics for an index, including total vector count and namespace breakdown. Optionally filter results with a metadata filter.

    **Usage**

    ```bash theme={null}
    pc index stats [flags]
    ```

    **Flags**

    | Long flag      | Short flag | Description                                                    |
    | :------------- | :--------- | :------------------------------------------------------------- |
    | `--index-name` | `-i`       | Index name (required)                                          |
    | `--filter`     | `-f`       | Metadata filter (inline JSON, `./path.json`, or `-` for stdin) |
    | `--json`       | `-j`       | Output in JSON format                                          |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Get stats for an index
    pc index stats -i my-index

    # Get stats with a metadata filter
    pc index stats -i my-index --filter '{"genre":{"$eq":"rock"}}'

    # Filter from file
    pc index stats -i my-index --filter ./filter.json

    # JSON output
    pc index stats -i my-index -j
    ```
  </Accordion>

  <Accordion title="pc index list (List all indexes)">
    **Description**

    Displays all indexes in your current target project, including various details.

    **Usage**

    ```bash theme={null}
    pc index list [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description                                         |
    | :-------- | :--------- | :-------------------------------------------------- |
    | `--json`  | `-j`       | Output in JSON format (includes full index details) |
    | `--wide`  | `-w`       | Show additional columns (host, embed, tags)         |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # List all indexes
    pc index list

    # Show additional details
    pc index list --wide

    # JSON output for scripting
    pc index list -j

    # After creating indexes
    pc index create -n test-1 -d 768 -m cosine -c aws -r us-east-1
    pc index list
    ```
  </Accordion>
</AccordionGroup>

### Namespaces

<AccordionGroup>
  <Accordion title="pc index namespace create (Create a namespace)">
    **Description**

    Creates a new namespace within an index. Namespaces allow you to partition vectors within an index.

    **Usage**

    ```bash theme={null}
    pc index namespace create [flags]
    ```

    **Flags**

    | Long flag      | Short flag | Description                                         |
    | :------------- | :--------- | :-------------------------------------------------- |
    | `--index-name` | `-i`       | Index name (required)                               |
    | `--name`       |            | Namespace name (required)                           |
    | `--schema`     |            | Metadata schema for the namespace (comma-separated) |
    | `--json`       | `-j`       | Output in JSON format                               |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Create a namespace
    pc index namespace create -i my-index --name tenant-a

    # Create with metadata schema (comma-separated list of filterable metadata fields)
    pc index namespace create -i my-index --name tenant-b --schema "category,brand"

    # JSON output
    pc index namespace create -i my-index --name tenant-c -j
    ```
  </Accordion>

  <Accordion title="pc index namespace delete (Delete a namespace)">
    **Description**

    Deletes a namespace and all its vectors from an index. This operation cannot be undone.

    **Usage**

    ```bash theme={null}
    pc index namespace delete [flags]
    ```

    **Flags**

    | Long flag             | Short flag | Description                                                            |
    | :-------------------- | :--------- | :--------------------------------------------------------------------- |
    | `--index-name`        | `-i`       | Index name (required)                                                  |
    | `--name`              |            | Namespace name (required); use `__default__` for the default namespace |
    | `--skip-confirmation` |            | Skip the deletion confirmation prompt                                  |
    | `--json`              | `-j`       | Output in JSON format (also skips the confirmation prompt)             |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Delete a namespace (prompts for confirmation)
    pc index namespace delete -i my-index --name tenant-a

    # Delete the default namespace
    pc index namespace delete -i my-index --name __default__

    # Skip the confirmation prompt
    pc index namespace delete -i my-index --name tenant-a --skip-confirmation
    ```

    <Warning>
      Deleting a namespace removes all vectors in that namespace. This operation cannot be undone.
    </Warning>
  </Accordion>

  <Accordion title="pc index namespace describe (Show namespace details)">
    **Description**

    Displays detailed information about a specific namespace, including record count and schema configuration.

    **Usage**

    ```bash theme={null}
    pc index namespace describe [flags]
    ```

    **Flags**

    | Long flag      | Short flag | Description                                                            |
    | :------------- | :--------- | :--------------------------------------------------------------------- |
    | `--index-name` | `-i`       | Index name (required)                                                  |
    | `--name`       |            | Namespace name (required); use `__default__` for the default namespace |
    | `--json`       | `-j`       | Output in JSON format                                                  |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Describe a namespace
    pc index namespace describe -i my-index --name tenant-a

    # Describe the default namespace
    pc index namespace describe -i my-index --name __default__

    # JSON output
    pc index namespace describe -i my-index --name tenant-a -j
    ```
  </Accordion>

  <Accordion title="pc index namespace list (List namespaces)">
    **Description**

    Lists all namespaces within an index, including vector counts.

    **Usage**

    ```bash theme={null}
    pc index namespace list [flags]
    ```

    **Flags**

    | Long flag            | Short flag | Description                    |
    | :------------------- | :--------- | :----------------------------- |
    | `--index-name`       | `-i`       | Index name (required)          |
    | `--limit`            | `-l`       | Maximum number of results      |
    | `--pagination-token` | `-p`       | Pagination token for next page |
    | `--prefix`           |            | Filter namespaces by prefix    |
    | `--json`             | `-j`       | Output in JSON format          |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # List all namespaces
    pc index namespace list -i my-index

    # Filter by prefix
    pc index namespace list -i my-index --prefix "tenant-"

    # Limit results
    pc index namespace list -i my-index --limit 10

    # JSON output
    pc index namespace list -i my-index -j
    ```
  </Accordion>
</AccordionGroup>

### Vectors

<AccordionGroup>
  <Accordion title="pc index vector delete (Delete vectors)">
    **Description**

    Deletes vectors from an index by ID, filter, or deletes all vectors in a namespace.

    **Usage**

    ```bash theme={null}
    pc index vector delete [flags]
    ```

    **Flags**

    | Long flag             | Short flag | Description                                                               |
    | :-------------------- | :--------- | :------------------------------------------------------------------------ |
    | `--index-name`        | `-i`       | Index name (required)                                                     |
    | `--namespace`         |            | Namespace to delete from (default: `__default__`)                         |
    | `--ids`               |            | Vector IDs to delete (inline JSON array, `./path.json`, or `-` for stdin) |
    | `--filter`            |            | Metadata filter (inline JSON, `./path.json`, or `-` for stdin)            |
    | `--all-vectors`       |            | Delete all vectors in the namespace                                       |
    | `--skip-confirmation` |            | Skip the confirmation prompt shown for `--all-vectors`                    |
    | `--json`              | `-j`       | Output in JSON format (also skips the confirmation prompt)                |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Delete specific vectors
    pc index vector delete -i my-index --ids '["id1"]'

    # Delete multiple vectors (inline JSON array, or JSON array in a file)
    pc index vector delete -i my-index --ids '["id1", "id2"]'

    # Delete by filter
    pc index vector delete -i my-index --filter '{"genre":"classical"}'

    # Delete all vectors in a namespace (prompts for confirmation)
    pc index vector delete -i my-index --namespace old-data --all-vectors

    # Delete all vectors without the prompt
    pc index vector delete -i my-index --namespace old-data --all-vectors --skip-confirmation
    ```

    <Note>
      Only `--all-vectors` prompts for confirmation. Targeted deletes with `--ids` or `--filter` proceed without a prompt. Pass `--skip-confirmation` (or `--json`) to bypass the `--all-vectors` prompt.
    </Note>

    <Warning>
      Vector deletion is permanent and cannot be undone.
    </Warning>
  </Accordion>

  <Accordion title="pc index vector fetch (Fetch vectors by ID or filter)">
    **Description**

    Retrieves vectors by their IDs or by a metadata filter, returning the vector values and metadata.

    **Usage**

    ```bash theme={null}
    pc index vector fetch [flags]
    ```

    **Flags**

    | Long flag            | Short flag | Description                                                              |
    | :------------------- | :--------- | :----------------------------------------------------------------------- |
    | `--index-name`       | `-i`       | Index name (required)                                                    |
    | `--namespace`        |            | Namespace to fetch from (default: `__default__`)                         |
    | `--ids`              |            | Vector IDs to fetch (inline JSON array, `./path.json`, or `-` for stdin) |
    | `--filter`           | `-f`       | Metadata filter (inline JSON, `./path.json`, or `-` for stdin)           |
    | `--limit`            | `-l`       | Maximum number of vectors to fetch                                       |
    | `--pagination-token` | `-p`       | Pagination token for next page                                           |
    | `--body`             |            | Request body JSON (inline, `./path.json`, or `-` for stdin)              |
    | `--json`             | `-j`       | Output in JSON format                                                    |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Fetch specific vectors by ID
    pc index vector fetch -i my-index --ids '["123","456","789"]'

    # Fetch from a file
    pc index vector fetch -i my-index --ids ./ids.json

    # Fetch by metadata filter
    pc index vector fetch -i my-index --filter '{"genre":{"$eq":"rock"}}'

    # Fetch from a namespace
    pc index vector fetch -i my-index --namespace tenant-a --ids '["doc-123"]'

    # JSON output
    pc index vector fetch -i my-index --ids '["vec1"]' -j
    ```

    <Note>
      Use either `--ids` or `--filter`, not both. When using `--ids`, pagination flags are not applicable.
    </Note>
  </Accordion>

  <Accordion title="pc index vector list (List vector IDs)">
    **Description**

    Lists vector IDs in a namespace with optional pagination.

    **Usage**

    ```bash theme={null}
    pc index vector list [flags]
    ```

    **Flags**

    | Long flag            | Short flag | Description                                     |
    | :------------------- | :--------- | :---------------------------------------------- |
    | `--index-name`       | `-i`       | Index name (required)                           |
    | `--namespace`        |            | Namespace to list from (default: `__default__`) |
    | `--limit`            | `-l`       | Maximum number of IDs to return                 |
    | `--pagination-token` | `-p`       | Pagination token for next page                  |
    | `--json`             | `-j`       | Output in JSON format                           |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # List vector IDs
    pc index vector list -i my-index

    # List from a namespace with limit
    pc index vector list -i my-index --namespace tenant-a --limit 50

    # JSON output
    pc index vector list -i my-index -j
    ```
  </Accordion>

  <Accordion title="pc index vector query (Query vectors)">
    **Description**

    Queries an index for similar vectors using dense vectors, sparse vectors, or vector ID.

    **Usage**

    ```bash theme={null}
    pc index vector query [flags]
    ```

    **Flags**

    | Long flag            | Short flag | Description                                                                       |
    | :------------------- | :--------- | :-------------------------------------------------------------------------------- |
    | `--index-name`       | `-i`       | Index name (required)                                                             |
    | `--namespace`        |            | Namespace to query (default: `__default__`)                                       |
    | `--id`               |            | Query by vector ID                                                                |
    | `--vector`           | `-v`       | Query vector values (inline JSON array, `./path.json`, or `-` for stdin)          |
    | `--sparse-indices`   |            | Sparse vector indices (inline JSON uint32 array, `./path.json`, or `-` for stdin) |
    | `--sparse-values`    |            | Sparse vector values (inline JSON array, `./path.json`, or `-` for stdin)         |
    | `--top-k`            | `-k`       | Number of results to return (default: 10)                                         |
    | `--filter`           | `-f`       | Metadata filter (inline JSON, `./path.json`, or `-` for stdin)                    |
    | `--include-values`   |            | Include vector values in results                                                  |
    | `--include-metadata` |            | Include metadata in results                                                       |
    | `--body`             |            | Request body JSON (inline, `./path.json`, or `-` for stdin)                       |
    | `--json`             | `-j`       | Output in JSON format                                                             |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Query by vector ID
    pc index vector query -i my-index --id "doc-123" -k 10 --include-metadata

    # Query by vector values
    pc index vector query -i my-index --vector '[0.1, 0.2, 0.3]' -k 25

    # Query with metadata filter
    pc index vector query -i my-index \
      --vector '[0.1, 0.2, 0.3]' \
      --filter '{"genre":{"$eq":"sci-fi"}}' \
      --include-metadata

    # Query from file (file contains a JSON array that specifies the query vector)
    pc index vector query -i my-index --vector ./embedding.json -k 20

    # Query with sparse vectors (inline)
    pc index vector query -i my-index \
      --sparse-indices '[0, 5, 12]' \
      --sparse-values '[0.5, 0.3, 0.8]' \
      -k 15

    # Query with sparse vectors from files
    # indices.json: [0, 5, 12]
    # values.json: [0.5, 0.3, 0.8]
    pc index vector query -i my-index \
      --sparse-indices ./indices.json \
      --sparse-values ./values.json \
      -k 15

    # Query from stdin (extract embedding from a document)
    # doc.json: {"id": "doc-123", "embedding": [0.1, 0.2, 0.3], "text": "..."}
    jq -c '.embedding' doc.json | pc index vector query -i my-index --vector - -k 10
    ```

    <Note>
      Use `--id`, `--vector`, or sparse vectors (`--sparse-indices` and `--sparse-values`) to specify what to query against. These options are mutually exclusive.
    </Note>
  </Accordion>

  <Accordion title="pc index vector update (Update vectors)">
    **Description**

    Updates a vector's values, sparse values, or metadata by ID, or updates metadata for multiple vectors matching a filter.

    **Usage**

    ```bash theme={null}
    pc index vector update [flags]
    ```

    **Flags**

    | Long flag          | Short flag | Description                                                                    |
    | :----------------- | :--------- | :----------------------------------------------------------------------------- |
    | `--index-name`     | `-i`       | Index name (required)                                                          |
    | `--namespace`      |            | Namespace containing the vector (default: `__default__`)                       |
    | `--id`             |            | Vector ID to update                                                            |
    | `--values`         |            | New vector values (inline JSON array, `./path.json`, or `-` for stdin)         |
    | `--sparse-indices` |            | New sparse indices (inline JSON uint32 array, `./path.json`, or `-` for stdin) |
    | `--sparse-values`  |            | New sparse values (inline JSON array, `./path.json`, or `-` for stdin)         |
    | `--metadata`       |            | New or updated metadata (inline JSON, `./path.json`, or `-` for stdin)         |
    | `--filter`         |            | Metadata filter for bulk update (inline JSON, `./path.json`, or `-` for stdin) |
    | `--dry-run`        |            | Preview how many records would be updated without applying changes             |
    | `--body`           |            | Request body JSON (inline, `./path.json`, or `-` for stdin)                    |
    | `--json`           | `-j`       | Output in JSON format                                                          |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Update metadata for a single vector
    pc index vector update -i my-index --id "vec1" --metadata '{"category":"updated"}'

    # Update values for a single vector
    pc index vector update -i my-index --id "vec1" --values '[0.2, 0.3, 0.4]'

    # Update sparse values
    # indices.json: [0, 5, 12]
    # values.json: [0.5, 0.3, 0.8]
    pc index vector update -i my-index --id "vec1" \
      --sparse-indices ./indices.json \
      --sparse-values ./values.json

    # Bulk update metadata by filter (preview first)
    pc index vector update -i my-index \
      --filter '{"genre":{"$eq":"sci-fi"}}' \
      --metadata '{"genre":"fantasy"}' \
      --dry-run

    # Apply the bulk update
    pc index vector update -i my-index \
      --filter '{"genre":{"$eq":"sci-fi"}}' \
      --metadata '{"genre":"fantasy"}'
    ```

    <Note>
      Use either `--id` for single vector updates or `--filter` for bulk updates. These options are mutually exclusive.
    </Note>
  </Accordion>

  <Accordion title="pc index vector upsert (Upsert vectors)">
    **Description**

    Inserts or updates vectors in an index from a JSON or JSONL file, or inline JSON. The CLI automatically batches vectors for efficient uploading. Files can contain any number of vectors—the CLI splits them into batches and sends multiple API requests as needed.

    **Usage**

    ```bash theme={null}
    pc index vector upsert [flags]
    ```

    **Flags**

    | Long flag      | Short flag | Description                                                                        |
    | :------------- | :--------- | :--------------------------------------------------------------------------------- |
    | `--index-name` | `-i`       | Index name (required)                                                              |
    | `--namespace`  |            | Namespace to upsert into (default: `__default__`)                                  |
    | `--body`       |            | Request body JSON or JSONL (inline, `./path.json[l]`, or `-` for stdin) (required) |
    | `--batch-size` | `-b`       | Size of batches to upsert (default: 500)                                           |
    | `--json`       | `-j`       | Output in JSON format                                                              |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Upsert from JSON file (with "vectors" array)
    # vectors.json: {"vectors": [{"id": "vec1", "values": [0.1, 0.2, 0.3], "metadata": {"genre": "comedy"}}]}
    pc index vector upsert -i my-index --body ./vectors.json

    # Upsert with inline JSON
    pc index vector upsert -i my-index --body '{"vectors": [{"id": "vec1", "values": [0.1, 0.2, 0.3], "metadata": {"genre": "comedy"}}]}'

    # Upsert from JSONL file (one vector per line)
    # vectors.jsonl: {"id": "vec1", "values": [0.1, 0.2, 0.3]}
    #                {"id": "vec2", "values": [0.4, 0.5, 0.6]}
    pc index vector upsert -i my-index --body ./vectors.jsonl

    # Upsert from stdin (same format as JSON or JSONL file)
    cat vectors.json | pc index vector upsert -i my-index --body -

    # Custom batch size (default: 500, max: 1000 per API request)
    pc index vector upsert -i my-index --body ./vectors.json --batch-size 1000
    ```

    <Note>
      **Batch size limits:** The API accepts up to 1000 vectors per request. The CLI defaults to batches of 500 vectors, but you can adjust this with `--batch-size` (up to 1000). Large files are automatically split into multiple batches.

      **File size:** There's no explicit file size limit—the CLI reads the entire file into memory and batches it automatically. Very large files are supported as long as they fit in available system memory.
    </Note>
  </Accordion>
</AccordionGroup>

### Records

<AccordionGroup>
  <Accordion title="pc index record search (Search records in an index)">
    **Description**

    Search an index namespace with a query text, query vector, or record ID and return the most similar records, along with their similarity scores. Optionally, rerank the initial results based on their relevance to the query.

    Searching with text is supported only for indexes with an integrated embedding configured. Searching with a query vector or record ID is supported for all indexes.

    Exactly one primary query mode must be provided:

    * `--inputs` — query text (requires an index with integrated embedding)
    * `--id` — use an existing record's vector as the query
    * `--vector` — provide a dense vector directly (all index types)
    * `--sparse-indices` + `--sparse-values` — sparse vector (all index types)

    Combine `--vector` with `--sparse-indices`/`--sparse-values` for hybrid search. Use `--body` to pass a full request object; flags take precedence over `--body` when both specify the same field.

    **Usage**

    ```bash theme={null}
    pc index record search [flags]
    ```

    **Flags**

    | Long flag          | Short flag | Description                                                                                                                                                     |
    | :----------------- | :--------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `--index-name`     | `-i`       | Name of the index to search (required)                                                                                                                          |
    | `--inputs`         |            | Query inputs for text search (inline JSON, `./path.json`, or `-` for stdin); requires integrated embedding. Mutually exclusive with `--id` and `--vector`.      |
    | `--id`             |            | Use an existing record's vector by ID for the query. Mutually exclusive with `--inputs` and `--vector`.                                                         |
    | `--vector`         | `-v`       | Dense vector values to search against (inline JSON float32 array, `./path.json`, or `-` for stdin). Mutually exclusive with `--inputs` and `--id`.              |
    | `--sparse-indices` |            | Sparse vector indices (inline JSON int32 array, `./path.json`, or `-` for stdin). Must be used together with `--sparse-values`.                                 |
    | `--sparse-values`  |            | Sparse vector values (inline JSON float32 array, `./path.json`, or `-` for stdin). Must be used together with `--sparse-indices`.                               |
    | `--top-k`          | `-k`       | Number of results to return (required)                                                                                                                          |
    | `--namespace`      |            | Namespace to search                                                                                                                                             |
    | `--filter`         |            | Metadata filter (inline JSON, `./path.json`, or `-` for stdin)                                                                                                  |
    | `--rerank`         |            | Re-score results using an inference model (inline JSON, `./path.json`, or `-` for stdin). Required fields: `model` (string), `rank_fields` (string array).      |
    | `--match-terms`    |            | Keyword terms filter for sparse integrated indexes (inline JSON, `./path.json`, or `-` for stdin). Required field: `terms` (string array). Requires `--inputs`. |
    | `--fields`         |            | Fields to return in results (inline JSON string array, `./path.json`, or `-` for stdin)                                                                         |
    | `--body`           |            | Full request body JSON (inline, `./path.json`, or `-` for stdin). Flags take precedence when both specify the same field.                                       |
    | `--json`           | `-j`       | Output in JSON format                                                                                                                                           |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Examples**

    ```bash theme={null}
    # Text search (integrated embedding indexes only)
    pc index record search --index-name my-index --inputs '{"text":"disease prevention"}' --top-k 10
    pc index record search --index-name my-index --inputs '{"text":"disease prevention"}' --namespace my-namespace --top-k 5
    pc index record search --index-name my-index --inputs '{"text":"disease prevention"}' --filter '{"category":"health"}' --top-k 10
    pc index record search --index-name my-index --inputs '{"text":"disease prevention"}' --fields '["_id","chunk_text","category"]' --top-k 10
    pc index record search --index-name my-index --inputs '{"text":"disease prevention"}' --rerank '{"model":"bge-reranker-v2-m3","rank_fields":["chunk_text"]}' --top-k 10
    pc index record search --index-name my-index --inputs '{"text":"disease prevention"}' --match-terms '{"terms":["vaccine","prevention"]}' --top-k 10

    # Search by record ID for query vector (all index types)
    pc index record search --index-name my-index --id rec-123 --top-k 10

    # Vector search (all index types)
    pc index record search --index-name my-index --vector '[0.1,0.2,0.3]' --top-k 10
    pc index record search --index-name my-index --sparse-indices '[1,5,9]' --sparse-values '[0.4,0.8,0.2]' --top-k 10
    pc index record search --index-name my-index --vector '[0.1,0.2,0.3]' --sparse-indices '[1,5,9]' --sparse-values '[0.4,0.8,0.2]' --top-k 10

    # Full request body (must include top_k in the body)
    pc index record search --index-name my-index --body ./search.json
    ```

    ```text CLI theme={null}
    Usage: 5 (read units)
    ID          SCORE       FIELDS
    rec-001     0.912340    {"category":"health","chunk_text":"vaccine research..."}
    rec-002     0.887210    {"category":"health","chunk_text":"disease prevention..."}
    ```
  </Accordion>

  <Accordion title="pc index record upsert (Upsert records into an integrated index)">
    **Description**

    Upsert records into an integrated index namespace from a JSON or JSONL payload.

    The `--body` flag accepts a JSON object containing a `"records"` array of `IntegratedRecord` objects, a raw JSON array of records, or a JSONL stream of records (one object per line). The value can be inline JSON, a path to a `.json` or `.jsonl` file, or `-` to read from stdin.

    Records are sent in batches. The default batch size is 96 (the API maximum). Use `--batch-size` to send smaller batches.

    **Usage**

    ```bash theme={null}
    pc index record upsert [flags]
    ```

    **Flags**

    | Long flag      | Short flag | Description                                                                             |
    | :------------- | :--------- | :-------------------------------------------------------------------------------------- |
    | `--index-name` | `-i`       | Name of the index to upsert into (required)                                             |
    | `--body`       |            | Request body JSON or JSONL (inline JSON, `./path.json[l]`, or `-` for stdin) (required) |
    | `--namespace`  |            | Namespace to upsert into                                                                |
    | `--batch-size` | `-b`       | Number of records per batch (default: `96`, max: `96`)                                  |
    | `--json`       | `-j`       | Output in JSON format                                                                   |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Examples**

    ```bash theme={null}
    # Upsert from a JSON file
    pc index record upsert --index-name my-index --body ./records.json

    # Upsert from a JSONL file into a specific namespace
    pc index record upsert --index-name my-index --namespace my-namespace --body ./records.jsonl

    # Upsert from stdin
    cat records.jsonl | pc index record upsert --index-name my-index --namespace my-namespace --body -
    ```
  </Accordion>
</AccordionGroup>

### Collections

<AccordionGroup>
  <Accordion title="pc index collection create (Create a collection from a pod-based index)">
    **Description**

    Creates a static copy of a pod-based index as a collection. Collections can be used to store a snapshot of an index's data for backup or migration purposes.

    **Usage**

    ```bash theme={null}
    pc index collection create [flags]
    ```

    **Flags**

    | Long flag  | Short flag | Description                                                 |
    | :--------- | :--------- | :---------------------------------------------------------- |
    | `--name`   | `-n`       | Name to give the collection (required)                      |
    | `--source` | `-s`       | Name of the pod-based index to use as the source (required) |
    | `--json`   | `-j`       | Output in JSON format                                       |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Create a collection from a pod-based index
    pc index collection create --name my-collection --source my-index
    ```

    ```text CLI theme={null}
    ATTRIBUTE     VALUE
    Name          my-collection
    State         Initializing
    Dimension     1536
    Size          0
    VectorCount   0
    Environment   us-east-1-aws
    ```
  </Accordion>

  <Accordion title="pc index collection delete (Delete a collection)">
    **Description**

    Deletes a collection permanently. This action cannot be undone.

    **Usage**

    ```bash theme={null}
    pc index collection delete [flags]
    ```

    **Flags**

    | Long flag             | Short flag | Description                                                |
    | :-------------------- | :--------- | :--------------------------------------------------------- |
    | `--name`              | `-n`       | Name of the collection to delete (required)                |
    | `--skip-confirmation` |            | Skip the deletion confirmation prompt                      |
    | `--json`              | `-j`       | Output in JSON format (also skips the confirmation prompt) |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Delete a collection (prompts for confirmation)
    pc index collection delete --name my-collection

    # Skip the confirmation prompt
    pc index collection delete --name my-collection --skip-confirmation
    ```

    <Note>
      This command prompts for confirmation before deleting. Pass `--skip-confirmation` (or `--json`) to bypass the prompt in non-interactive contexts.
    </Note>
  </Accordion>

  <Accordion title="pc index collection describe (Describe a collection by name)">
    **Description**

    Returns detailed information about a single collection, including its state, dimension, size, vector count, and environment.

    **Usage**

    ```bash theme={null}
    pc index collection describe [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description                                   |
    | :-------- | :--------- | :-------------------------------------------- |
    | `--name`  | `-n`       | Name of the collection to describe (required) |
    | `--json`  | `-j`       | Output in JSON format                         |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Describe a collection
    pc index collection describe --name my-collection
    ```

    ```text CLI theme={null}
    ATTRIBUTE     VALUE
    Name          my-collection
    State         Ready
    Dimension     1536
    Size          104857600
    VectorCount   10000
    Environment   us-east-1-aws
    ```
  </Accordion>

  <Accordion title="pc index collection list (List collections in your project)">
    **Description**

    Lists all collections in your current project, sorted alphabetically by name.

    **Usage**

    ```bash theme={null}
    pc index collection list [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description           |
    | :-------- | :--------- | :-------------------- |
    | `--json`  | `-j`       | Output in JSON format |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # List all collections
    pc index collection list
    ```

    ```text CLI theme={null}
    NAME             DIMENSION   SIZE        STATUS   VECTORS   ENVIRONMENT
    my-collection    1536        104857600   Ready    10000     us-east-1-aws
    ```
  </Accordion>
</AccordionGroup>

### Backups

<AccordionGroup>
  <Accordion title="pc index backup create (Create a backup)">
    **Description**

    Creates a backup of a serverless index. Backups are static copies that only consume storage.

    **Usage**

    ```bash theme={null}
    pc index backup create [flags]
    ```

    **Flags**

    | Long flag       | Short flag | Description                                                          |
    | :-------------- | :--------- | :------------------------------------------------------------------- |
    | `--index-name`  | `-i`       | Name of the index to back up (required)                              |
    | `--name`        |            | Human-readable label for the backup (the backup ID is always a UUID) |
    | `--description` | `-d`       | Description for the backup                                           |
    | `--json`        | `-j`       | Output in JSON format                                                |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Create a backup
    pc index backup create -i my-index

    # Create with name and description
    pc index backup create -i my-index --name "nightly-backup" -d "Nightly backup before deployment"

    # JSON output
    pc index backup create -i my-index -j
    ```
  </Accordion>

  <Accordion title="pc index backup delete (Delete a backup)">
    **Description**

    Permanently deletes a backup. This operation cannot be undone.

    **Usage**

    ```bash theme={null}
    pc index backup delete [flags]
    ```

    **Flags**

    | Long flag             | Short flag | Description                                                |
    | :-------------------- | :--------- | :--------------------------------------------------------- |
    | `--id`                | `-i`       | Backup ID to delete (required)                             |
    | `--skip-confirmation` |            | Skip the deletion confirmation prompt                      |
    | `--json`              | `-j`       | Output in JSON format (also skips the confirmation prompt) |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Delete a backup by ID (prompts for confirmation)
    pc index backup delete -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f

    # Skip the confirmation prompt
    pc index backup delete -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f --skip-confirmation
    ```

    <Note>
      This command prompts for confirmation before deleting. Pass `--skip-confirmation` (or `--json`) to bypass the prompt in non-interactive contexts.
    </Note>

    <Warning>
      Backup deletion is permanent and cannot be undone.
    </Warning>
  </Accordion>

  <Accordion title="pc index backup describe (Show backup details)">
    **Description**

    Displays detailed information about a specific backup.

    **Usage**

    ```bash theme={null}
    pc index backup describe [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description                      |
    | :-------- | :--------- | :------------------------------- |
    | `--id`    | `-i`       | Backup ID to describe (required) |
    | `--json`  | `-j`       | Output in JSON format            |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Describe a backup
    pc index backup describe -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f

    # JSON output
    pc index backup describe -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f -j
    ```
  </Accordion>

  <Accordion title="pc index backup list (List backups)">
    **Description**

    Lists backups in the current project, optionally filtered by index name.

    **Usage**

    ```bash theme={null}
    pc index backup list [flags]
    ```

    **Flags**

    | Long flag            | Short flag | Description                    |
    | :------------------- | :--------- | :----------------------------- |
    | `--index-name`       | `-i`       | Filter backups by index name   |
    | `--limit`            | `-l`       | Maximum number of results      |
    | `--pagination-token` | `-p`       | Pagination token for next page |
    | `--json`             | `-j`       | Output in JSON format          |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # List all backups in the project
    pc index backup list

    # List backups for a specific index
    pc index backup list --index-name my-index

    # Limit results
    pc index backup list --limit 10

    # JSON output
    pc index backup list -j
    ```
  </Accordion>

  <Accordion title="pc index restore (Restore an index from a backup)">
    **Description**

    Creates a new index from a backup.

    **Usage**

    ```bash theme={null}
    pc index restore [flags]
    ```

    **Flags**

    | Long flag               | Short flag | Description                                          |
    | :---------------------- | :--------- | :--------------------------------------------------- |
    | `--id`                  | `-i`       | Backup ID (UUID) to restore from (required)          |
    | `--name`                | `-n`       | Name for the new index (required)                    |
    | `--deletion-protection` |            | Enable deletion protection - `enabled` or `disabled` |
    | `--tags`                | `-t`       | Tags to apply to the new index (key=value pairs)     |
    | `--json`                | `-j`       | Output in JSON format                                |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Restore an index from a backup
    pc index restore -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f -n restored-index

    # Restore with tags and deletion protection
    pc index restore -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f -n restored-index \
      --tags env=prod,team=search \
      --deletion-protection enabled

    # JSON output
    pc index restore -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f -n restored-index -j
    ```
  </Accordion>

  <Accordion title="pc index restore describe (Show restore job details)">
    **Description**

    Displays the status and details of a restore job.

    **Usage**

    ```bash theme={null}
    pc index restore describe [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description                           |
    | :-------- | :--------- | :------------------------------------ |
    | `--id`    | `-i`       | Restore job ID to describe (required) |
    | `--json`  | `-j`       | Output in JSON format                 |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Describe a restore job
    pc index restore describe -i rj-abc123

    # JSON output
    pc index restore describe -i rj-abc123 -j
    ```
  </Accordion>

  <Accordion title="pc index restore list (List restore jobs)">
    **Description**

    Lists all restore jobs in the current project.

    **Usage**

    ```bash theme={null}
    pc index restore list [flags]
    ```

    **Flags**

    | Long flag            | Short flag | Description                    |
    | :------------------- | :--------- | :----------------------------- |
    | `--limit`            | `-l`       | Maximum number of results      |
    | `--pagination-token` | `-p`       | Pagination token for next page |
    | `--json`             | `-j`       | Output in JSON format          |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # List restore jobs
    pc index restore list

    # Limit results
    pc index restore list --limit 10

    # JSON output
    pc index restore list -j
    ```
  </Accordion>
</AccordionGroup>

### Imports

<AccordionGroup>
  <Accordion title="pc index import start (Start an import from a storage URI)">
    **Description**

    Start an import that loads vector data from a storage provider into a serverless index. The URI must begin with the scheme of a supported provider (for example, `s3://`).

    For private buckets, configure a storage integration in the Pinecone console and pass the integration ID with `--integration-id`.

    Use `--error-mode` to control behavior when records fail: `continue` skips failing records and keeps going; `abort` stops the import on first error. Defaults to `continue`.

    **Usage**

    ```bash theme={null}
    pc index import start [flags]
    ```

    **Flags**

    | Long flag          | Short flag | Description                                                           |
    | :----------------- | :--------- | :-------------------------------------------------------------------- |
    | `--index-name`     | `-i`       | Name of the index to import into (required)                           |
    | `--uri`            | `-u`       | URI of the data to import, for example `s3://bucket/path/` (required) |
    | `--integration-id` |            | Storage integration ID for private buckets                            |
    | `--error-mode`     |            | How to handle record errors: `continue` (default) or `abort`          |
    | `--json`           | `-j`       | Output in JSON format                                                 |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Examples**

    ```bash theme={null}
    # Start an import from a public S3 bucket
    pc index import start --index-name my-index --uri s3://my-bucket/data/

    # Start an import from a private bucket using a storage integration
    pc index import start --index-name my-index --uri s3://my-bucket/data/ --integration-id intg-123

    # Abort on the first error instead of continuing
    pc index import start --index-name my-index --uri s3://my-bucket/data/ --error-mode abort

    # JSON output
    pc index import start --index-name my-index --uri s3://my-bucket/data/ -j
    ```

    ```text CLI theme={null}
    Import imp-abc123 started.
    ATTRIBUTE    VALUE
    Import ID    imp-abc123
    ```
  </Accordion>

  <Accordion title="pc index import describe (Describe an import operation)">
    **Description**

    Show the current status and details of an import operation, including
    percent complete, records imported, and any error messages.

    **Usage**

    ```bash theme={null}
    pc index import describe [flags]
    ```

    **Flags**

    | Long flag      | Short flag | Description                                        |
    | :------------- | :--------- | :------------------------------------------------- |
    | `--index-name` | `-i`       | Name of the index the import belongs to (required) |
    | `--id`         |            | ID of the import to describe (required)            |
    | `--json`       | `-j`       | Output in JSON format                              |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Describe an import operation
    pc index import describe --index-name my-index --id import-123

    # JSON output
    pc index import describe --index-name my-index --id import-123 -j
    ```

    ```text CLI theme={null}
    ATTRIBUTE         VALUE
    Import ID         import-123
    Status            InProgress
    URI               s3://my-bucket/data/
    Percent Complete  45.0%
    Records Imported  450
    Created At        2024-01-15 12:00:00
    Finished At       -
    Error             None
    ```
  </Accordion>

  <Accordion title="pc index import list (List import operations for an index)">
    **Description**

    List bulk import operations for the given index, with optional pagination.

    **Usage**

    ```bash theme={null}
    pc index import list [flags]
    ```

    **Flags**

    | Long flag            | Short flag | Description                                               |
    | :------------------- | :--------- | :-------------------------------------------------------- |
    | `--index-name`       | `-i`       | Name of the index to list imports for (required)          |
    | `--limit`            | `-l`       | Maximum number of imports to return                       |
    | `--pagination-token` | `-p`       | Pagination token to continue a previous listing operation |
    | `--json`             | `-j`       | Output in JSON format                                     |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Examples**

    ```bash theme={null}
    # List all imports for an index
    pc index import list --index-name my-index

    # List imports with a page size limit
    pc index import list --index-name my-index --limit 10

    # Continue paginating from a previous call
    pc index import list --index-name my-index --pagination-token eyJ...

    # JSON output
    pc index import list --index-name my-index -j
    ```

    ```text CLI theme={null}
    IMPORT ID     STATUS      URI                     PERCENT  RECORDS  CREATED              FINISHED
    imp-abc123    Completed   s3://my-bucket/data/    100.0%   1000     2024-01-15 12:00:00  2024-01-15 12:05:00
    imp-def456    InProgress  s3://other-bucket/data/ 45.0%    450      2024-01-15 13:00:00  -
    ```
  </Accordion>

  <Accordion title="pc index import cancel (Cancel an in-progress import operation)">
    **Description**

    Cancel an import operation that is currently pending or in progress.
    Already-completed or failed imports cannot be canceled.

    **Usage**

    ```bash theme={null}
    pc index import cancel [flags]
    ```

    **Flags**

    | Long flag      | Short flag | Description                                        |
    | :------------- | :--------- | :------------------------------------------------- |
    | `--index-name` | `-i`       | Name of the index the import belongs to (required) |
    | `--id`         |            | ID of the import to cancel (required)              |
    | `--json`       | `-j`       | Output in JSON format                              |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Cancel an import operation
    pc index import cancel --index-name my-index --id import-123

    # JSON output
    pc index import cancel --index-name my-index --id import-123 -j
    ```

    ```text CLI theme={null}
    Import import-123 canceled.
    ```
  </Accordion>
</AccordionGroup>

### Projects

<AccordionGroup>
  <Accordion title="pc project create (Create a new project)">
    **Description**

    Creates a new project in your [target organization](/reference/cli/target-context), using the specified configuration.

    **Usage**

    ```bash theme={null}
    pc project create [flags]
    ```

    **Flags**

    | Long flag            | Short flag | Description                                                    |
    | :------------------- | :--------- | :------------------------------------------------------------- |
    | `--force-encryption` |            | Enable encryption with CMEK                                    |
    | `--json`             | `-j`       | Output in JSON format                                          |
    | `--name`             | `-n`       | Project name (required)                                        |
    | `--target`           |            | Automatically target the project in the CLI after it's created |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Basic project creation
    pc project create -n "demo-project"
    ```
  </Accordion>

  <Accordion title="pc project delete (Delete a project)">
    **Description**

    Permanently deletes a project and all its resources. This operation cannot be undone.

    **Usage**

    ```bash theme={null}
    pc project delete [flags]
    ```

    **Flags**

    | Long flag             | Short flag | Description                                                 |
    | :-------------------- | :--------- | :---------------------------------------------------------- |
    | `--id`                | `-i`       | Project ID (optional, uses target project if not specified) |
    | `--json`              | `-j`       | Output in JSON format                                       |
    | `--skip-confirmation` |            | Skip confirmation prompt                                    |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Delete target project
    pc project delete

    # Delete specific project
    pc project delete -i proj-abc123

    # Skip confirmation
    pc project delete -i proj-abc123 --skip-confirmation
    ```

    <Note>
      Must delete all indexes and collections in the project first. If the deleted project is your current target, set a new target after deleting it.
    </Note>
  </Accordion>

  <Accordion title="pc project describe (Show project details)">
    **Description**

    Displays detailed information about a specific project, including various details.

    **Usage**

    ```bash theme={null}
    pc project describe [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description           |
    | :-------- | :--------- | :-------------------- |
    | `--id`    | `-i`       | Project ID (required) |
    | `--json`  | `-j`       | Output in JSON format |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Describe a project
    pc project describe -i proj-abc123

    # JSON output
    pc project describe -i proj-abc123 --json

    # Find ID and describe
    pc project list
    pc project describe -i proj-abc123
    ```
  </Accordion>

  <Accordion title="pc project list (List all projects)">
    **Description**

    Displays all projects in your [target organization](/reference/cli/target-context), including various details.

    **Usage**

    ```bash theme={null}
    pc project list [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description           |
    | :-------- | :--------- | :-------------------- |
    | `--json`  | `-j`       | Output in JSON format |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # List all projects
    pc project list

    # JSON output
    pc project list --json

    # List after login
    pc auth login
    pc auth target -o "my-org"
    pc project list
    ```
  </Accordion>

  <Accordion title="pc project update (Update project settings)">
    **Description**

    Modifies the configuration of the [target project](/reference/cli/target-context), or a specific project ID.

    **Usage**

    ```bash theme={null}
    pc project update [flags]
    ```

    **Flags**

    | Long flag            | Short flag | Description                         |
    | :------------------- | :--------- | :---------------------------------- |
    | `--force-encryption` | `-f`       | Enable/disable encryption with CMEK |
    | `--id`               | `-i`       | Project ID (required)               |
    | `--json`             | `-j`       | Output in JSON format               |
    | `--name`             | `-n`       | New project name                    |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Update name
    pc project update -i proj-abc123 -n "new-name"
    ```
  </Accordion>
</AccordionGroup>

### Organizations

<AccordionGroup>
  <Accordion title="pc organization delete (Delete an organization)">
    **Description**

    Permanently deletes an organization and all its resources. This operation cannot be undone.

    **Usage**

    ```bash theme={null}
    pc organization delete [flags]
    ```

    **Flags**

    | Long flag             | Short flag | Description                |
    | :-------------------- | :--------- | :------------------------- |
    | `--id`                | `-i`       | Organization ID (required) |
    | `--json`              | `-j`       | Output in JSON format      |
    | `--skip-confirmation` |            | Skip confirmation prompt   |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Delete an organization
    pc organization delete -i org-abc123

    # Skip confirmation
    pc organization delete -i org-abc123 --skip-confirmation
    ```

    <Note>
      This is a highly destructive action. Deletion is permanent. If the deleted organization is your current [target](/reference/cli/target-context), set a new target after deleting.
    </Note>
  </Accordion>

  <Accordion title="pc organization describe (Show organization details)">
    **Description**

    Displays detailed information about a specific organization, including name, ID, creation date, payment status, plan, and support tier.

    **Usage**

    ```bash theme={null}
    pc organization describe [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description                |
    | :-------- | :--------- | :------------------------- |
    | `--id`    | `-i`       | Organization ID (required) |
    | `--json`  | `-j`       | Output in JSON format      |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Describe an organization
    pc organization describe -i org-abc123

    # JSON output
    pc organization describe -i org-abc123 --json

    # Find ID and describe
    pc organization list
    pc organization describe -i org-abc123
    ```
  </Accordion>

  <Accordion title="pc organization list (List organizations)">
    **Description**

    Displays all organizations that the authenticated user has access to, including name, ID, creation date, payment status, plan, and support tier.

    **Usage**

    ```bash theme={null}
    pc organization list [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description           |
    | :-------- | :--------- | :-------------------- |
    | `--json`  | `-j`       | Output in JSON format |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # List all organizations
    pc organization list

    # JSON output
    pc organization list --json

    # List after login
    pc auth login
    pc organization list
    ```
  </Accordion>

  <Accordion title="pc organization update (Update organization settings)">
    **Description**

    Modifies the configuration of the [target organization](/reference/cli/target-context), or a specific organization ID.

    **Usage**

    ```bash theme={null}
    pc organization update [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description                |
    | :-------- | :--------- | :------------------------- |
    | `--id`    | `-i`       | Organization ID (required) |
    | `--json`  | `-j`       | Output in JSON format      |
    | `--name`  | `-n`       | New organization name      |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Update name
    pc organization update -i org-abc123 -n "new-name"

    # Verify changes
    pc organization update -i org-abc123 -n "Acme Corp"
    pc organization describe -i org-abc123
    ```
  </Accordion>
</AccordionGroup>

### API keys

<AccordionGroup>
  <Accordion title="pc api-key create (Create a new API key)">
    **Description**

    Creates a new API key for the current [target project](/reference/cli/target-context) or a specific project ID. Optionally stores the key locally for CLI use.

    **Usage**

    ```bash theme={null}
    pc api-key create [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description                                                                             |
    | :-------- | :--------- | :-------------------------------------------------------------------------------------- |
    | `--id`    | `-i`       | Project ID (optional, uses target project if not specified)                             |
    | `--json`  | `-j`       | Output in JSON format                                                                   |
    | `--name`  | `-n`       | Key name (required)                                                                     |
    | `--roles` |            | Roles to assign (default: `ProjectEditor`)                                              |
    | `--store` |            | Store the key locally for CLI use (automatically replaces any existing CLI-managed key) |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Basic key creation
    pc api-key create -n "my-key"

    # Create and store locally
    pc api-key create -n "my-key" --store

    # Create with specific role
    pc api-key create -n "my-key" --store --roles ProjectEditor

    # Create for specific project
    pc api-key create -n "my-key" -i proj-abc123
    ```

    <Note>
      API keys are scoped to a specific organization and project.
    </Note>
  </Accordion>

  <Accordion title="pc api-key delete (Delete an API key)">
    **Description**

    Permanently deletes an API key. Applications using this key immediately lose access.

    **Usage**

    ```bash theme={null}
    pc api-key delete [flags]
    ```

    **Flags**

    | Long flag             | Short flag | Description              |
    | :-------------------- | :--------- | :----------------------- |
    | `--id`                | `-i`       | API key ID (required)    |
    | `--skip-confirmation` |            | Skip confirmation prompt |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Delete an API key
    pc api-key delete -i key-abc123

    # Skip confirmation
    pc api-key delete -i key-abc123 --skip-confirmation

    # Delete and clean up local storage
    pc api-key delete -i key-abc123
    pc auth local-keys prune --skip-confirmation
    ```

    <Note>
      Deletion is permanent. Applications using this key immediately lose access to Pinecone.
    </Note>
  </Accordion>

  <Accordion title="pc api-key describe (Show API key details)">
    **Description**

    Displays detailed information about a specific API key, including its name, ID, project ID, and roles.

    **Usage**

    ```bash theme={null}
    pc api-key describe [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description           |
    | :-------- | :--------- | :-------------------- |
    | `--id`    | `-i`       | API key ID (required) |
    | `--json`  | `-j`       | Output in JSON format |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Describe an API key
    pc api-key describe -i key-abc123

    # JSON output
    pc api-key describe -i key-abc123 --json

    # Find ID and describe
    pc api-key list
    pc api-key describe -i key-abc123
    ```

    <Note>
      Does not display the actual key value.
    </Note>
  </Accordion>

  <Accordion title="pc api-key list (List all API keys)">
    **Description**

    Displays a list of all of the [target project's](/reference/cli/target-context) API keys, as found in  Pinecone (regardless of whether they are stored locally by the CLI). Displays various details about each key, including name, ID, project ID, and roles.

    **Usage**

    ```bash theme={null}
    pc api-key list [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description                                                 |
    | :-------- | :--------- | :---------------------------------------------------------- |
    | `--id`    | `-i`       | Project ID (optional, uses target project if not specified) |
    | `--json`  | `-j`       | Output in JSON format                                       |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # List keys for target project
    pc api-key list

    # List for specific project
    pc api-key list -i proj-abc123

    # JSON output
    pc api-key list --json
    ```

    <Note>
      Does not display key values.
    </Note>
  </Accordion>

  <Accordion title="pc api-key update (Update API key settings)">
    **Description**

    Updates the name and roles of an API key.

    **Usage**

    ```bash theme={null}
    pc api-key update [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description           |
    | :-------- | :--------- | :-------------------- |
    | `--id`    | `-i`       | API key ID (required) |
    | `--json`  | `-j`       | Output in JSON format |
    | `--name`  | `-n`       | New key name          |
    | `--roles` | `-r`       | Roles to assign       |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Update name
    pc api-key update -i key-abc123 -n "new-name"

    # Update roles
    pc api-key update -i key-abc123 -r ProjectEditor

    # Verify changes
    pc api-key update -i key-abc123 -n "production-key"
    pc api-key describe -i key-abc123
    ```

    <Note>
      Cannot change the actual key. If you need a different key, create a new one.
    </Note>
  </Accordion>
</AccordionGroup>

### Config

<AccordionGroup>
  <Accordion title="pc config list (List all configuration settings and their current values)">
    **Description**

    Lists all CLI configuration settings and their current values. Sensitive values like `api-key` are masked by default; use `--reveal` to see the full value. Hidden settings such as `environment` are included when `--all` is passed.

    **Usage**

    ```bash theme={null}
    pc config list [flags]
    ```

    **Flags**

    | Long flag  | Short flag | Description                                               |
    | :--------- | :--------- | :-------------------------------------------------------- |
    | `--reveal` |            | Reveal the full value for sensitive settings like api-key |
    | `--json`   | `-j`       | Output in JSON format                                     |
    | `--all`    |            | Include hidden settings such as environment               |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    pc config list
    pc config list --all
    pc config list --reveal
    pc config list --json
    ```

    ```text CLI theme={null}
    KEY         VALUE             ENV VAR NAME        ENV VAR OVERRIDE  DESCRIPTION
    api-key     ****abcd****      PINECONE_API_KEY     false             Default API key for authenticating with Pinecone
    color       true                                                     Enable colored output
    ```
  </Accordion>

  <Accordion title="pc config get <key> (Get the current value of a configuration setting)">
    **Description**

    Gets the current value of a configuration setting. Valid keys are: `api-key`, `color`, `environment`. Sensitive values like `api-key` are masked by default; use `--reveal` to see the full value.

    **Usage**

    ```bash theme={null}
    pc config get <key> [flags]
    ```

    **Flags**

    | Long flag  | Short flag | Description                                               |
    | :--------- | :--------- | :-------------------------------------------------------- |
    | `--reveal` |            | Reveal the full value for sensitive settings like api-key |
    | `--json`   | `-j`       | Output in JSON format                                     |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    pc config get api-key
    pc config get api-key --reveal
    pc config get environment
    pc config get color
    ```
  </Accordion>

  <Accordion title="pc config describe <key> (Show detailed information about a configuration setting)">
    **Description**

    Displays detailed information about a specific CLI configuration setting, including its current value, whether an environment variable is overriding it, and valid values. Valid keys are: `api-key`, `color`, `environment`.

    **Usage**

    ```bash theme={null}
    pc config describe <key> [flags]
    ```

    **Flags**

    | Long flag  | Short flag | Description                                               |
    | :--------- | :--------- | :-------------------------------------------------------- |
    | `--reveal` |            | Reveal the full value for sensitive settings like api-key |
    | `--json`   | `-j`       | Output in JSON format                                     |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    pc config describe api-key
    pc config describe color
    pc config describe color --json
    ```

    ```text CLI theme={null}
    KEY               api-key
    VALUE             ****abcd****
    ENV VAR NAME      $PINECONE_API_KEY
    ENV VAR OVERRIDE  false
    SENSITIVE         true
    DESCRIPTION       Default API key for authenticating with Pinecone
    ```
  </Accordion>

  <Accordion title="pc config set <key> <value> (Set a configuration value)">
    **Description**

    Sets a CLI configuration value. Valid keys are: `api-key`, `color`, `environment`. The value is persisted to the local config file.

    **Usage**

    ```bash theme={null}
    pc config set <key> <value> [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description           |
    | :-------- | :--------- | :-------------------- |
    | `--json`  | `-j`       | Output in JSON format |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    pc config set api-key pcsk_...
    pc config set environment staging
    pc config set color false
    ```
  </Accordion>

  <Accordion title="pc config unset <key> (Reset a configuration value to its default)">
    **Description**

    Resets a CLI configuration value to its default. Valid keys are: `api-key`, `color`, `environment`.

    **Usage**

    ```bash theme={null}
    pc config unset <key> [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description           |
    | :-------- | :--------- | :-------------------- |
    | `--json`  | `-j`       | Output in JSON format |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    pc config unset api-key
    pc config unset color
    ```
  </Accordion>
</AccordionGroup>


# CLI quickstart
Source: https://docs.pinecone.io/reference/cli/quickstart

Pinecone CLI quickstart for installing pc, authenticating, and managing indexes, vectors, and data imports directly from your terminal.

The Pinecone CLI (`pc`) lets you manage Pinecone resources directly from your terminal.

## Install

<Tabs>
  <Tab title="macOS (Homebrew)">
    ```bash theme={null}
    brew tap pinecone-io/tap
    brew install pinecone-io/tap/pinecone
    ```
  </Tab>

  <Tab title="Other platforms">
    Pre-built binaries for macOS, Linux, and Windows are available on the [GitHub Releases page](https://github.com/pinecone-io/cli/releases).

    | Platform | Architectures                          |
    | :------- | :------------------------------------- |
    | macOS    | Intel (x86\_64), Apple Silicon (ARM64) |
    | Linux    | x86\_64, ARM64, i386                   |
    | Windows  | x86\_64, i386                          |
  </Tab>
</Tabs>

## Authenticate

```bash theme={null}
pc auth login
```

Visit the URL in your terminal to sign in. The CLI automatically sets your default organization and project.

To target a different org/project:

```bash theme={null}
pc target -o "my-org" -p "my-project"
```

<Tip>
  For CI/CD or automation, you can also authenticate with a [service account](/reference/cli/authentication#service-account) or [API key](/reference/cli/authentication#api-key).
</Tip>

## Manage indexes

```bash theme={null}
# List indexes
pc index list

# Create an index
pc index create -n my-index -d 3 -m cosine -c aws -r us-east-1

# Get index details
pc index describe -i my-index

# Get index statistics
pc index stats -i my-index
```

## Work with vectors

```bash theme={null}
# Upsert vectors (from file or inline JSON)
pc index vector upsert -i my-index \
  --body '{"vectors": [{"id": "vec1", "values": [0.1, 0.2, 0.3], "metadata": {"genre": "comedy"}}]}'

# Import from a large dataset in object storage (S3, GCS, Azure)
pc index import start -i my-index --uri s3://my-bucket/data/

# Check the progress of an import operation
pc index import list --i my-index
pc index import describe --i my-index --id import-123

# Query (vector can be inline or in a file)
pc index vector query -i my-index \
  --vector '[0.1, 0.2, 0.3]' \
  --top-k 10 \
  --include-metadata

# Fetch by ID (from file or inline JSON)
pc index vector fetch -i my-index --ids '["vec1","vec2"]'

# List vector IDs from an index
pc index vector list -i my-index
```

## Manage namespaces

```bash theme={null}
# List namespaces
pc index namespace list -i my-index

# Create a namespace
pc index namespace create -i my-index --name tenant-a

# Delete a namespace
pc index namespace delete -i my-index --name tenant-a
```

## Back up and restore

```bash theme={null}
# Create a backup
pc index backup create -i my-index --name "my-index-backup"

# List backups (show index, backup name, backup ID, etc.)
pc index backup list -i my-index

# Restore from backup (by ID, not name)
pc index restore -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f -n restored-index
```

## JSON output

Add `-j` to any command for JSON output:

```bash theme={null}
pc index list -j
pc index describe -i my-index -j
```

## Getting help

Use `-h` or `--help` with any command to see available options:

```bash theme={null}
pc -h
pc index -h
pc index create -h
```

## Next steps

* [Command reference](/reference/cli/command-reference) — Full list of commands and flags
* [Authentication](/reference/cli/authentication) — Service accounts, API keys, and auth priority
* [Target context](/reference/cli/target-context) — How org/project targeting works


# CLI target context
Source: https://docs.pinecone.io/reference/cli/target-context

Pinecone CLI: The CLI's **target context** determines which organization and project your commands operate on. You must authenticate before setting target.

The CLI's **target context** determines which organization and project your commands operate on. You must [authenticate](/reference/cli/authentication) before setting target context.

## Flags

| Flag                | Short | Default | Description                                                                       |
| ------------------- | ----- | ------- | --------------------------------------------------------------------------------- |
| `--org`             | `-o`  | —       | Target organization by name. Mutually exclusive with `--organization-id`.         |
| `--organization-id` | —     | —       | Target organization by ID. Mutually exclusive with `--org`.                       |
| `--project`         | `-p`  | —       | Target project by name. Mutually exclusive with `--project-id`.                   |
| `--project-id`      | —     | —       | Target project by ID. Mutually exclusive with `--project`.                        |
| `--show`            | `-s`  | `false` | Show the current target context.                                                  |
| `--clear`           | —     | `false` | Clear the stored target context.                                                  |
| `--json`            | `-j`  | `false` | Output as JSON. In non-TTY environments (CI/CD, pipes), JSON output is automatic. |

<Note>
  `--org` and `--organization-id` are mutually exclusive — use one or the other. The same applies to `--project` and `--project-id`.
</Note>

## How operations use target context

| Operation type                   | Scope                                    |
| -------------------------------- | ---------------------------------------- |
| Control plane (indexes, backups) | Target project                           |
| Data plane (vectors, namespaces) | Target project + specified index         |
| Admin API (organizations)        | No target context needed                 |
| Admin API (projects)             | Target organization                      |
| Admin API (API keys)             | Target project (unless `--id` specified) |

## Target context by auth method

### User login

After `pc auth login`, the CLI auto-targets your default organization and its first project.

```bash theme={null}
# Change target
pc target -o "my-org" -p "my-project"
```

### Service account

**Via CLI command:** After `pc auth configure --client-id --client-secret`, the CLI auto-targets the service account's organization. For the project:

* If one project exists, it's auto-targeted
* If multiple exist, you're prompted (or use `--project-id`)
* If none exist, create one and target it manually

**Via environment variables:** If using `PINECONE_CLIENT_ID` and `PINECONE_CLIENT_SECRET` without running `pc auth configure`, no target context is set automatically. Run `pc target` to set it.

```bash theme={null}
# Change project (org is fixed to the service account's org)
pc target -p "my-project"

# Or select interactively
pc target
```

### API key

<Warning>
  When using an API key, control plane and data plane operations use the **key's org/project scope**, not the CLI's stored target context. The `pc target --show` output does not reflect what these operations actually use.
</Warning>

API keys are scoped to a specific org and project and cannot access resources outside that scope.

Admin API operations still use your user login or service account credentials (API keys can't authenticate Admin API calls).

## Managing target context

```bash theme={null}
pc target --show   # View current target
pc target --clear  # Clear target context
```

### JSON mode and non-TTY environments

Running `pc target --json` with no targeting flags returns the current target context as a JSON object. This is a local-state read — **no authentication is required**:

```bash theme={null}
pc target --json
```

In non-TTY environments (CI/CD pipelines, shell pipes, scripts), JSON output is automatic — the same as passing `--json` explicitly. You do not need to add the flag in automation contexts.

Use `--organization-id` and `--project-id` (instead of name flags) to set context reliably in scripts, since IDs are stable and unaffected by renames:

```bash theme={null}
pc target --organization-id "org-abc123" --project-id "proj-xyz789" --json
```


# Pinecone SDKs overview
Source: https://docs.pinecone.io/reference/pinecone-sdks

Browse official Pinecone SDKs for Python, Node.js, Java, and Go, including the version mappings between SDK releases and API versions.

## Pinecone SDKs

Official Pinecone SDKs provide convenient access to the [Pinecone APIs](/reference/api/introduction).

<CardGroup>
  <Card title="Python SDK" icon="python" href="/reference/sdks/python/overview" />

  <Card title="Node.js SDK" icon="node-js" href="/reference/sdks/node/overview" />

  <Card title="Java SDK" icon="java" href="/reference/sdks/java/overview" />

  <Card title="Go SDK" icon="golang" href="/reference/sdks/go/overview" />
</CardGroup>

## SDK versions

SDK versions are pinned to specific [API versions](/reference/api/versioning). When a new API version is released, a new version of the SDK is also released.

The mappings between API versions and SDK versions are as follows:

|                                               | `2026-04`   | `2025-10` | `2025-04` | `2025-01` | `2024-10` | `2024-07`     | `2024-04` |
| --------------------------------------------- | :---------- | :-------- | :-------- | :-------- | :-------- | :------------ | :-------- |
| [Python SDK](/reference/sdks/python/overview) | v9.x        | v8.x      | v7.x      | v6.x      | v5.3.x    | v5.0.x-v5.2.x | v4.x      |
| [Node.js SDK](/reference/sdks/node/overview)  | v8.x        | v7.x      | v6.x      | v5.x      | v4.x      | v3.x          | v2.x      |
| [Java SDK](/reference/sdks/java/overview)     | Coming soon | v6.x      | v5.x      | v4.x      | v3.x      | v2.x          | v1.x      |
| [Go SDK](/reference/sdks/go/overview)         | v6.x        | v5.x      | v4.x      | v3.x      | v2.x      | v1.x          | v0.x      |

When a new stable API version is released, you should upgrade your SDK to the latest version to ensure compatibility with the latest API changes.

<Note>
  The Java SDK targeting API version `2026-04` will be available soon.
</Note>

## Limitations

While Pinecone tracks read unit usage with decimal precision, the Pinecone API and SDKs round these values up to the nearest whole number in query, fetch, and list responses. For example, if a query uses 0.45 read units, the API and SDKs will report it as 1 read unit.

For precise read unit reporting, see [index-level metrics](/guides/production/monitoring) or the organization-wide [Usage dashboard](/guides/manage-cost/monitor-usage-and-costs#monitor-organization-level-usage-and-costs).

## Community SDKs

Find community-contributed SDKs for Pinecone. These libraries are not supported by Pinecone.

* [Ruby SDK](https://github.com/ScotterC/pinecone) (contributed by [ScotterC](https://github.com/ScotterC))

* [Scala SDK](https://github.com/cequence-io/pinecone-scala) (contributed by [cequence-io](https://github.com/cequence-io))

* [PHP SDK](https://github.com/probots-io/pinecone-php) (contributed by [protobots-io](https://github.com/probots-io))


# Pinecone Go SDK
Source: https://docs.pinecone.io/reference/sdks/go/overview

Install and use the Pinecone Go SDK to manage indexes and namespaces, upsert vectors, run semantic search, and call the Admin and Inference APIs from Go.

<Tip>
  For installation instructions and usage examples, see the [Go SDK documentation](https://github.com/pinecone-io/go-pinecone). To report an issue or request a feature, [file an issue on GitHub](https://github.com/pinecone-io/go-pinecone/issues).
</Tip>

## Requirements

The Pinecone Go SDK requires a Go version with [modules](https://go.dev/wiki/Modules) support.

## SDK versions

SDK versions are pinned to specific [API versions](/reference/api/versioning). When a new API version is released, a new version of the SDK is also released.

The mappings between API versions and Go SDK versions are as follows:

| API version | SDK version |
| :---------- | :---------- |
| `2026-04`   | v6.x        |
| `2025-10`   | v5.x        |
| `2025-04`   | v4.x        |
| `2025-01`   | v3.x        |
| `2024-10`   | v2.x        |
| `2024-07`   | v1.x        |
| `2024-04`   | v0.x        |

When a new stable API version is released, you should upgrade your SDK to the latest version to ensure compatibility with the latest API changes.

## Install

To install the latest version of the [Go SDK](https://github.com/pinecone-io/go-pinecone), add a dependency to the current module:

```shell theme={null}
go get github.com/pinecone-io/go-pinecone/v6/pinecone
```

To install a specific version of the Go SDK, run the following command:

```shell theme={null}
go get github.com/pinecone-io/go-pinecone/v6/pinecone@<version>
```

To check your SDK version, run the following command:

```shell theme={null}
go list -u -m all | grep go-pinecone
```

## Upgrade

<Warning>
  Before upgrading to `v3.0.0` or later, update all relevant code to account for the breaking changes explained [here](/release-notes/2025#2025-02-07-4).
</Warning>

Each major version carries its version number in the module path, so crossing a major requires updating the import path in every file that uses the SDK. For example, moving from `v4` to `v6` means changing:

```go theme={null}
// before
import "github.com/pinecone-io/go-pinecone/v4/pinecone"

// after
import "github.com/pinecone-io/go-pinecone/v6/pinecone"
```

Apart from the module path, `v5.0.0` and `v6.0.0` are backward compatible with the release lines before them.

If you already have the Go SDK, upgrade to the latest version as follows:

```shell theme={null}
go get -u github.com/pinecone-io/go-pinecone/v6/pinecone@latest
```

## Initialize

Once installed, you can import the SDK and then use an [API key](/guides/production/security-overview#api-keys) to initialize a client instance:

```Go theme={null}
package main

import (
    "context"
    "log"

    "github.com/pinecone-io/go-pinecone/v6/pinecone"
)

func main() {
    ctx := context.Background()

    pc, err := pinecone.NewClient(pinecone.NewClientParams{
        ApiKey: "YOUR_API_KEY",
    })
    if err != nil {
        log.Fatalf("Failed to create Client: %v", err)
    }
} 
```

To manage organizations, projects, API keys, and [role-based access control](/guides/production/manage-rbac), initialize an `AdminClient` with [service account](/guides/organizations/manage-service-accounts) credentials instead:

```Go theme={null}
package main

import (
    "context"
    "log"
    "os"

    "github.com/pinecone-io/go-pinecone/v6/pinecone"
)

func main() {
    ctx := context.Background()

    adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
        ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
        ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
    })
    if err != nil {
        log.Fatalf("Failed to create AdminClient: %v", err)
    }
}
```


# Reference
Source: https://docs.pinecone.io/reference/sdks/go/reference

Reference documentation for the Pinecone Go SDK, including client setup, types, and methods for managing indexes and vector data operations.



# OpenTelemetry support
Source: https://docs.pinecone.io/reference/sdks/java/open-telemetry

Monitor Pinecone Java SDK operations with OpenTelemetry metrics for client latency, server processing time, and errors via Prometheus.

The Pinecone Java SDK provides built-in support for capturing per-operation response metadata, making it straightforward to monitor your Pinecone usage with [OpenTelemetry](https://opentelemetry.io/) or any other observability system.

With this feature, you can track client-side latency, server processing time, network overhead, error rates, and more for every data plane operation your application makes.

## How it all fits together

The SDK's observability support is designed to be flexible. You don't need to adopt the entire observability stack at once -- start simple and add layers as your needs grow.

Here are the components involved and how they relate to each other:

* **Pinecone Java SDK**: Exposes a `ResponseMetadataListener` callback, a plain Java interface with no external dependencies. At its simplest, you can log the metadata to the console. No additional tools required.
* **[OpenTelemetry](https://opentelemetry.io/) (OTel)**: An open standard and SDK for producing structured telemetry data (metrics, traces, logs). If you want standardized metrics that follow [semantic conventions](https://opentelemetry.io/docs/specs/semconv/database/database-spans/), you add the OTel SDK and wire it to the listener. This is optional.
* **OTel Collector**: A vendor-neutral service that receives telemetry from your app and forwards it to a storage backend. Optional -- many setups export directly from the app to a backend.
* **Prometheus**: A time-series database that stores metrics, making them queryable over time. One popular storage option.
* **Grafana**: A visualization and dashboarding tool that queries Prometheus (or other backends) and displays charts and alerts. One popular visualization option.

A common setup chains these together:

```
Your App (OTel SDK) → OTel Collector → Prometheus (storage) → Grafana (visualization)
```

<Note>
  This is just one example pipeline. You can substitute Datadog, New Relic, or any OTel-compatible backend. You can also skip OTel entirely and use [Micrometer](#example-micrometerprometheus), custom logging, or any approach that suits your stack.
</Note>

## Response metadata listener

The Java SDK captures response metadata through a `ResponseMetadataListener` -- a functional interface you provide when building the Pinecone client. The listener is called after each data plane operation completes (whether it succeeds or fails), and receives a `ResponseMetadata` object containing timing, status, and context information.

The SDK itself has no OpenTelemetry dependency. You bring your own observability library and decide what to do with the metadata.

### Supported operations

The following data plane operations are instrumented, for both synchronous (`Index`) and asynchronous (`AsyncIndex`) usage:

| Operation | Description                |
| --------- | -------------------------- |
| `upsert`  | Insert or update vectors   |
| `query`   | Search for similar vectors |
| `fetch`   | Retrieve vectors by ID     |
| `update`  | Update vector metadata     |
| `delete`  | Delete vectors             |

### Available metadata

Each `ResponseMetadata` object provides the following fields:

| Method                   | Description                                        | OTel attribute            |
| ------------------------ | -------------------------------------------------- | ------------------------- |
| `getOperationName()`     | Operation type (e.g., `upsert`, `query`)           | `db.operation.name`       |
| `getIndexName()`         | Pinecone index name                                | `pinecone.index_name`     |
| `getNamespace()`         | Namespace (empty string if default)                | `db.namespace`            |
| `getServerAddress()`     | Pinecone server host                               | `server.address`          |
| `getClientDurationMs()`  | Total round-trip time in ms (always available)     | --                        |
| `getServerDurationMs()`  | Server processing time in ms (may be `null`)       | --                        |
| `getNetworkOverheadMs()` | Client minus server duration in ms (may be `null`) | --                        |
| `getStatus()`            | `"success"` or `"error"`                           | `status`                  |
| `getGrpcStatusCode()`    | Raw gRPC status code (e.g., `OK`, `UNAVAILABLE`)   | `db.response.status_code` |
| `getErrorType()`         | Error category, or `null` if successful            | `error.type`              |

Possible `errorType` values: `validation`, `connection`, `server`, `rate_limit`, `timeout`, `auth`, `not_found`, `unknown`.

### Recommended metrics

If you're recording OTel metrics, the SDK example project uses these metric names, which follow [OTel semantic conventions for database clients](https://opentelemetry.io/docs/specs/semconv/database/database-spans/):

| Metric                                | Type      | Unit | Description                     |
| ------------------------------------- | --------- | ---- | ------------------------------- |
| `db.client.operation.duration`        | Histogram | ms   | Client-measured round-trip time |
| `pinecone.server.processing.duration` | Histogram | ms   | Server processing time          |
| `db.client.operation.count`           | Counter   | --   | Total number of operations      |

## Quick start: Simple logging

The simplest way to use the listener is to log the metadata directly. This requires no additional dependencies beyond the Pinecone SDK:

```java theme={null}
import io.pinecone.clients.Pinecone;

Pinecone client = new Pinecone.Builder("PINECONE_API_KEY")
    .withResponseMetadataListener(metadata -> {
        System.out.printf("Operation: %s | Client: %dms | Server: %sms | Network: %sms | Status: %s%n",
            metadata.getOperationName(),
            metadata.getClientDurationMs(),
            metadata.getServerDurationMs(),
            metadata.getNetworkOverheadMs(),
            metadata.getStatus());
    })
    .build();
```

Once configured, every data plane operation automatically triggers the listener:

```java theme={null}
Index index = client.getIndexConnection("my-index");
index.upsert("id-1", Arrays.asList(0.1f, 0.2f, 0.3f));
// Output: Operation: upsert | Client: 47ms | Server: 40ms | Network: 7ms | Status: success
```

## Quick start: OpenTelemetry integration

To record structured metrics with OpenTelemetry, add the OTel SDK dependencies and wire a metrics recorder to the listener.

### 1. Add dependencies

Add the following to your `pom.xml`:

```xml theme={null}
<dependencies>
    <!-- Pinecone SDK -->
    <dependency>
        <groupId>io.pinecone</groupId>
        <artifactId>pinecone-client</artifactId>
        <version>LATEST</version>
    </dependency>

    <!-- OpenTelemetry SDK -->
    <dependency>
        <groupId>io.opentelemetry</groupId>
        <artifactId>opentelemetry-sdk</artifactId>
    </dependency>
    <dependency>
        <groupId>io.opentelemetry</groupId>
        <artifactId>opentelemetry-sdk-metrics</artifactId>
    </dependency>

    <!-- OTLP exporter (sends metrics to an OTel Collector or compatible backend) -->
    <dependency>
        <groupId>io.opentelemetry</groupId>
        <artifactId>opentelemetry-exporter-otlp</artifactId>
    </dependency>
</dependencies>

<!-- Use the OTel BOM to manage versions -->
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.opentelemetry</groupId>
            <artifactId>opentelemetry-bom</artifactId>
            <version>1.35.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
```

### 2. Create a metrics recorder

The SDK's [example project](https://github.com/pinecone-io/pinecone-java-client/tree/main/examples/java-otel-metrics) includes a reusable `PineconeMetricsRecorder` class you can copy into your project. It implements `ResponseMetadataListener` and records all three recommended metrics with proper OTel attributes:

```java theme={null}
import io.opentelemetry.api.common.AttributeKey;
import io.opentelemetry.api.common.Attributes;
import io.opentelemetry.api.common.AttributesBuilder;
import io.opentelemetry.api.metrics.LongCounter;
import io.opentelemetry.api.metrics.LongHistogram;
import io.opentelemetry.api.metrics.Meter;
import io.pinecone.configs.ResponseMetadata;
import io.pinecone.configs.ResponseMetadataListener;

public class PineconeMetricsRecorder implements ResponseMetadataListener {

    private static final AttributeKey<String> DB_SYSTEM = AttributeKey.stringKey("db.system");
    private static final AttributeKey<String> DB_OPERATION_NAME = AttributeKey.stringKey("db.operation.name");
    private static final AttributeKey<String> DB_NAMESPACE = AttributeKey.stringKey("db.namespace");
    private static final AttributeKey<String> PINECONE_INDEX_NAME = AttributeKey.stringKey("pinecone.index_name");
    private static final AttributeKey<String> SERVER_ADDRESS = AttributeKey.stringKey("server.address");
    private static final AttributeKey<String> STATUS = AttributeKey.stringKey("status");
    private static final AttributeKey<String> ERROR_TYPE = AttributeKey.stringKey("error.type");

    private final LongHistogram clientDurationHistogram;
    private final LongHistogram serverDurationHistogram;
    private final LongCounter operationCounter;

    public PineconeMetricsRecorder(Meter meter) {
        this.clientDurationHistogram = meter.histogramBuilder("db.client.operation.duration")
                .setDescription("Duration of Pinecone operations from client perspective")
                .setUnit("ms")
                .ofLongs()
                .build();

        this.serverDurationHistogram = meter.histogramBuilder("pinecone.server.processing.duration")
                .setDescription("Server processing time from x-pinecone-response-duration-ms header")
                .setUnit("ms")
                .ofLongs()
                .build();

        this.operationCounter = meter.counterBuilder("db.client.operation.count")
                .setDescription("Total number of Pinecone operations")
                .setUnit("{operation}")
                .build();
    }

    @Override
    public void onResponse(ResponseMetadata metadata) {
        AttributesBuilder attributesBuilder = Attributes.builder()
                .put(DB_SYSTEM, "pinecone")
                .put(DB_OPERATION_NAME, metadata.getOperationName())
                .put(PINECONE_INDEX_NAME, metadata.getIndexName())
                .put(SERVER_ADDRESS, metadata.getServerAddress())
                .put(STATUS, metadata.getStatus());

        String namespace = metadata.getNamespace();
        if (namespace != null && !namespace.isEmpty()) {
            attributesBuilder.put(DB_NAMESPACE, namespace);
        }

        if (!metadata.isSuccess() && metadata.getErrorType() != null) {
            attributesBuilder.put(ERROR_TYPE, metadata.getErrorType());
        }

        Attributes attributes = attributesBuilder.build();

        clientDurationHistogram.record(metadata.getClientDurationMs(), attributes);

        Long serverDuration = metadata.getServerDurationMs();
        if (serverDuration != null) {
            serverDurationHistogram.record(serverDuration, attributes);
        }

        operationCounter.add(1, attributes);
    }
}
```

### 3. Wire it into the Pinecone client

Initialize the OTel SDK, create the recorder, and pass it to the Pinecone client builder:

```java theme={null}
import io.opentelemetry.api.metrics.Meter;
import io.opentelemetry.sdk.OpenTelemetrySdk;
import io.opentelemetry.sdk.metrics.SdkMeterProvider;
import io.opentelemetry.sdk.metrics.export.PeriodicMetricReader;
import io.opentelemetry.exporter.otlp.metrics.OtlpGrpcMetricExporter;
import io.pinecone.clients.Pinecone;

// Set up OTel with OTLP exporter
OtlpGrpcMetricExporter exporter = OtlpGrpcMetricExporter.builder()
    .setEndpoint("http://localhost:4317")
    .build();

SdkMeterProvider meterProvider = SdkMeterProvider.builder()
    .registerMetricReader(PeriodicMetricReader.builder(exporter).build())
    .build();

OpenTelemetrySdk openTelemetry = OpenTelemetrySdk.builder()
    .setMeterProvider(meterProvider)
    .build();

// Create the metrics recorder
Meter meter = openTelemetry.getMeter("pinecone.client");
PineconeMetricsRecorder recorder = new PineconeMetricsRecorder(meter);

// Build the Pinecone client with the recorder
Pinecone client = new Pinecone.Builder("PINECONE_API_KEY")
    .withResponseMetadataListener(recorder)
    .build();

// Use the client normally -- metrics are recorded automatically
Index index = client.getIndexConnection("my-index");
index.upsert("id-1", Arrays.asList(0.1f, 0.2f, 0.3f));
index.query(3, Arrays.asList(0.1f, 0.2f, 0.3f));
```

<Tip>
  For a complete runnable example with Docker Compose, Prometheus, and Grafana, see the [java-otel-metrics example project](https://github.com/pinecone-io/pinecone-java-client/tree/main/examples/java-otel-metrics) in the SDK repository.
</Tip>

## Example: Micrometer/Prometheus

If your application uses [Micrometer](https://micrometer.io/) (common in Spring Boot), you can wire the listener to Micrometer instead of the OTel SDK:

```java theme={null}
import io.micrometer.core.instrument.MeterRegistry;
import io.micrometer.core.instrument.Timer;
import io.pinecone.clients.Pinecone;
import java.util.concurrent.TimeUnit;

Pinecone client = new Pinecone.Builder("PINECONE_API_KEY")
    .withResponseMetadataListener(metadata -> {
        Timer.builder("pinecone.client.duration")
            .tag("operation", metadata.getOperationName())
            .tag("index", metadata.getIndexName())
            .tag("status", metadata.getStatus())
            .register(meterRegistry)
            .record(metadata.getClientDurationMs(), TimeUnit.MILLISECONDS);
    })
    .build();
```

## Visualizing metrics

Once your metrics are flowing to a backend, you can build dashboards to monitor your Pinecone operations. If you're using Prometheus and Grafana, here are some useful queries:

**P50 and P95 client latency:**

```promql theme={null}
histogram_quantile(0.5, sum(rate(db_client_operation_duration_milliseconds_bucket[5m])) by (le))
histogram_quantile(0.95, sum(rate(db_client_operation_duration_milliseconds_bucket[5m])) by (le))
```

**P95 latency by operation type:**

```promql theme={null}
histogram_quantile(0.95, sum(rate(db_client_operation_duration_milliseconds_bucket[5m])) by (le, db_operation_name))
```

**Operation count by type:**

```promql theme={null}
sum by (db_operation_name) (db_client_operation_count_total)
```

## Understanding the latency breakdown

The `ResponseMetadata` object provides three timing values that help you pinpoint the source of latency issues:

| Component        | Method                   | What it measures                                                                                                                             |
| ---------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| Client duration  | `getClientDurationMs()`  | Total round-trip time from request start to response completion. Always available.                                                           |
| Server duration  | `getServerDurationMs()`  | Time the Pinecone backend spent processing the request. Extracted from the `x-pinecone-response-duration-ms` response header. May be `null`. |
| Network overhead | `getNetworkOverheadMs()` | The difference: client duration minus server duration. Includes network latency, serialization, and deserialization. May be `null`.          |

Use these values to diagnose performance issues:

* **High server duration**: The bottleneck is on the Pinecone backend. Consider optimizing your query (e.g., reducing `topK`, using metadata filters), or check the [Pinecone status page](https://status.pinecone.io/).
* **High network overhead**: The bottleneck is in the network path between your application and Pinecone. Consider deploying your application closer to your index's cloud region, or check for network issues.

## Limitations

* **Data plane operations only.** Control plane operations (e.g., creating or deleting indexes) are not currently instrumented.
* **Bulk import operations** are not yet instrumented.
* **Server duration may be unavailable.** The `getServerDurationMs()` method returns `null` if the `x-pinecone-response-duration-ms` header is not present in the response.
* **Synchronous callback.** The listener is called synchronously after the gRPC response is received. Keep implementations lightweight and non-blocking to avoid adding latency to your operations. For heavy processing, queue the metadata for async handling.
* **Exceptions are swallowed.** Exceptions thrown by the listener are logged but do not affect the operation result.

## Best practices

* **Keep listeners lightweight.** Record metrics or enqueue work -- don't do I/O or heavy computation in the callback.
* **Follow OTel semantic conventions.** Use the attribute names shown in the [recommended metrics](#recommended-metrics) table for interoperability with standard dashboards and tooling.
* **Monitor both client and server duration.** Tracking both lets you separate Pinecone backend performance from network conditions.
* **Set alerts on error rates.** Use the `status` and `error.type` attributes to build alerts for elevated error rates across operations.


# Pinecone Java SDK
Source: https://docs.pinecone.io/reference/sdks/java/overview

Install and use the Pinecone Java SDK to manage indexes and namespaces, upsert vectors, run semantic search, and call the Admin and Inference APIs from Java.

<Tip>
  For installation instructions and usage examples, see the [Pinecone Java SDK documentation](https://github.com/pinecone-io/pinecone-java-client). To report an issue or request a feature, [file an issue on GitHub](https://github.com/pinecone-io/pinecone-java-client/issues).
</Tip>

## Requirements

The Pinecone Java SDK requires Java 1.8 or later.

## SDK versions

SDK versions are pinned to specific [API versions](/reference/api/versioning). When a new API version is released, a new version of the SDK is also released.

The mappings between API versions and Java SDK versions are as follows:

| API version | SDK version |
| :---------- | :---------- |
| `2025-04`   | v5.x        |
| `2025-01`   | v4.x        |
| `2024-10`   | v3.x        |
| `2024-07`   | v2.x        |
| `2024-04`   | v1.x        |

When a new stable API version is released, you should upgrade your SDK to the latest version to ensure compatibility with the latest API changes.

## Install

To install the latest version of the [Java SDK](https://github.com/pinecone-io/pinecone-java-client), add a dependency to the current module:

```shell Java theme={null}
# Maven
<dependency>
  <groupId>io.pinecone</groupId>
  <artifactId>pinecone-client</artifactId>
  <version>5.0.0</version>
</dependency>

# Gradle
implementation "io.pinecone:pinecone-client:5.0.0"
```

Alternatively, you can download the standalone uberjar [pinecone-client-4.0.0-all.jar](https://repo1.maven.org/maven2/io/pinecone/pinecone-client/4.0.0/pinecone-client-4.0.0-all.jar), which bundles the Pinecone SDK and all dependencies together. You can include this in your classpath like you do with any third-party JAR without having to obtain the `pinecone-client` dependencies separately.

## Upgrade

<Warning>
  Before upgrading to `v4.0.0`, update all relevant code to account for the breaking changes explained [here](/release-notes/2025#2025-02-07-3).
</Warning>

If you are already using the Java SDK, upgrade the dependency in the current module to the latest version:

```shell Java theme={null}
# Maven
<dependency>
  <groupId>io.pinecone</groupId>
  <artifactId>pinecone-client</artifactId>
  <version>5.0.0</version>
</dependency>

# Gradle
implementation "io.pinecone:pinecone-client:5.0.0"
```

## Initialize

Once installed, you can import the SDK and then use an [API key](/guides/production/security-overview#api-keys) to initialize a client instance:

```Java theme={null}
import io.pinecone.clients.Pinecone;
import org.openapitools.db_control.client.model.*;

public class InitializeClientExample {
    public static void main(String[] args) {
        Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build();
    }
}
```

## Observability

The Java SDK supports capturing per-operation response metadata for all data plane operations, including client-side latency, server processing time, network overhead, and error details. You can use this metadata with [OpenTelemetry](https://opentelemetry.io/), Micrometer, or any other observability system to monitor your Pinecone usage in production.

For setup instructions and examples, see [OpenTelemetry support](/reference/sdks/java/open-telemetry).


# Reference
Source: https://docs.pinecone.io/reference/sdks/java/reference

Reference documentation for the Pinecone Java SDK, including client setup, types, and methods for managing indexes and vector data operations.



# Pinecone Node.js SDK
Source: https://docs.pinecone.io/reference/sdks/node/overview

Install and use the Pinecone Node.js and TypeScript SDK to manage indexes, upsert vectors, run semantic search, and call the Admin and Inference APIs.

<Tip>
  For installation instructions, usage examples, and reference information, see the [Pinecone Node.js SDK documentation](https://sdk.pinecone.io/typescript/). To report an issue or request a feature, [file an issue on GitHub](https://github.com/pinecone-io/pinecone-ts-client/issues).
</Tip>

## Requirements

The Pinecone Node SDK requires TypeScript 4.1 or later and Node 18.x or later.

## SDK versions

SDK versions are pinned to specific [API versions](/reference/api/versioning). When a new API version is released, a new version of the SDK is also released.

The mappings between API versions and Node.js SDK versions are as follows:

| API version | SDK version |
| :---------- | :---------- |
| `2026-04`   | v8.x        |
| `2025-10`   | v7.x        |
| `2025-04`   | v6.x        |
| `2025-01`   | v5.x        |
| `2024-10`   | v4.x        |
| `2024-07`   | v3.x        |
| `2024-04`   | v2.x        |

When a new stable API version is released, you should upgrade your SDK to the latest version to ensure compatibility with the latest API changes.

## Install

To install the latest version of the [Node.js SDK](https://github.com/pinecone-io/pinecone-ts-client), written in TypeScript, run the following command:

```Shell theme={null}
npm install @pinecone-database/pinecone
```

To check your SDK version, run the following command:

```Shell theme={null}
npm list | grep @pinecone-database/pinecone
```

## Upgrade

If you already have the Node.js SDK, upgrade to the latest version as follows:

```Shell theme={null}
npm install @pinecone-database/pinecone@latest
```

## Initialize

Once installed, you can import the library and then use an [API key](/guides/projects/manage-api-keys) to initialize a client instance:

```JavaScript theme={null}
import { Pinecone } from '@pinecone-database/pinecone';

const pc = new Pinecone({
    apiKey: 'YOUR_API_KEY'
});
```

To manage organizations, projects, API keys, and [role-based access control](/guides/production/manage-rbac), initialize an `AdminClient` with [service account](/guides/organizations/manage-service-accounts) credentials instead. This requires v8.2.0 or later:

```JavaScript theme={null}
import { AdminClient } from '@pinecone-database/pinecone';

// Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
const admin = new AdminClient();
```

You can also pass `clientId` and `clientSecret` directly to the constructor instead of setting environment variables.

## Proxy configuration

If your network setup requires you to interact with Pinecone through a proxy, you can pass a custom `ProxyAgent` from the [`undici` library](https://undici.nodejs.org/#/). Below is an example of how to construct an `undici` `ProxyAgent` that routes network traffic through a [`mitm` proxy server](https://mitmproxy.org/) while hitting Pinecone's `/indexes` endpoint.

<Note>
  The following strategy relies on Node's native [`fetch`](https://nodejs.org/docs/latest/api/globals.html#fetch) implementation, released in Node v16 and stabilized in Node v21. If you are running Node versions 18-21, you may experience issues stemming from the instability of the feature. There are currently no known issues related to proxying in Node v18+.
</Note>

```JavaScript JavaScript theme={null}
import {
  Pinecone,
  type PineconeConfiguration,
} from '@pinecone-database/pinecone';
import { Dispatcher, ProxyAgent } from 'undici';
import * as fs from 'fs';

const cert = fs.readFileSync('path/to/mitmproxy-ca-cert.pem');

const client = new ProxyAgent({
  uri: 'https://your-proxy.com',
  requestTls: {
    port: 'YOUR_PROXY_SERVER_PORT',
    ca: cert,
    host: 'YOUR_PROXY_SERVER_HOST',
  },
});

const customFetch = (
  input: string | URL | Request,
  init: RequestInit | undefined
) => {
  return fetch(input, {
    ...init,
    dispatcher: client as Dispatcher,
    keepalive: true,  # optional
  });
};

const config: PineconeConfiguration = {
  apiKey:
    'YOUR_API_KEY',
  fetchApi: customFetch,
};

const pc = new Pinecone(config);

const indexes = async () => {
  return await pc.listIndexes();
};

indexes().then((response) => {
  console.log('My indexes: ', response);
});
```


# Reference
Source: https://docs.pinecone.io/reference/sdks/node/reference

Reference documentation for the Pinecone Node.js SDK, including client setup, types, and methods for managing indexes and vector data operations.



# Pinecone Python SDK
Source: https://docs.pinecone.io/reference/sdks/python/overview

Install and use the Pinecone SDK for Pinecone Python SDK: auth, typed clients, and API operations. For installation instructions, usage examples, and.

<Tip>
  For installation instructions, usage examples, and reference information, see the [Pinecone Python SDK documentation](https://sdk.pinecone.io/python/). To report an issue or request a feature, [file an issue on GitHub](https://github.com/pinecone-io/pinecone-python-client/issues).
</Tip>

The Pinecone Python SDK is distributed on PyPI using the package name `pinecone`. By default, the `pinecone` package has a minimal set of dependencies and interacts with Pinecone via HTTP requests. However, you can install the following extras to unlock additional functionality:

* `pinecone[grpc]` adds dependencies on `grpcio` and related libraries needed to run data operations such as upserts and queries over [gRPC](https://grpc.io/) for a modest performance improvement.

* `pinecone[asyncio]` adds a dependency on `aiohttp` and enables usage of `async` methods for use with [asyncio](https://docs.python.org/3/library/asyncio.html). For more details, see [Async requests](#async-requests).

## Requirements

The Pinecone Python SDK requires Python 3.9 or later. It has been tested with CPython versions from 3.9 to 3.13.

## SDK versions

SDK versions are pinned to specific [API versions](/reference/api/versioning). When a new API version is released, a new version of the SDK is also released.

The mappings between API versions and Python SDK versions are as follows:

| API version | SDK version   |
| :---------- | :------------ |
| `2025-04`   | v7.x          |
| `2025-01`   | v6.x          |
| `2024-10`   | v5.3.x        |
| `2024-07`   | v5.0.x-v5.2.x |
| `2024-04`   | v4.x          |

When a new stable API version is released, you should upgrade your SDK to the latest version to ensure compatibility with the latest API changes.

## Install

To install the latest version of the [Python SDK](https://github.com/pinecone-io/pinecone-python-client), run the following command:

```shell theme={null}
# Install the latest version
pip install pinecone

# Install the latest version with gRPC extras
pip install "pinecone[grpc]"

# Install the latest version with asyncio extras
pip install "pinecone[asyncio]"
```

To install a specific version of the Python SDK, run the following command:

```shell pip theme={null}
# Install a specific version
pip install pinecone==<version>

# Install a specific version with gRPC extras
pip install "pinecone[grpc]"==<version>

# Install a specific version with asyncio extras
pip install "pinecone[asyncio]"==<version>
```

To check your SDK version, run the following command:

```shell pip theme={null}
pip show pinecone
```

<Note>
  To use the [Inference API](/reference/api/introduction#inference), you must be on version 5.0.0 or later.
</Note>

### Install the Pinecone Assistant Python plugin

As of Python SDK v7.0.0, the `pinecone-plugin-assistant` package is included by default. It is only necessary to install the package if you are using a version of the Python SDK prior to v7.0.0.

```shell HTTP theme={null}
pip install --upgrade pinecone pinecone-plugin-assistant
```

## Upgrade

<Warning>
  Before upgrading to `v6.0.0`, update all relevant code to account for the breaking changes explained [here](https://github.com/pinecone-io/pinecone-python-client/blob/main/docs/upgrading.md).

  Also, make sure to upgrade using the `pinecone` package name instead of `pinecone-client`; upgrading with the latter will not work as of `v6.0.0`.
</Warning>

If you already have the Python SDK, upgrade to the latest version as follows:

```shell theme={null}
# Upgrade to the latest version
pip install pinecone --upgrade

# Upgrade to the latest version with gRPC extras
pip install "pinecone[grpc]" --upgrade

# Upgrade to the latest version with asyncio extras
pip install "pinecone[asyncio]" --upgrade
```

## Initialize

Once installed, you can import the library and then use an [API key](/guides/projects/manage-api-keys) to initialize a client instance:

<CodeGroup>
  ```Python HTTP theme={null}
  from pinecone import Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")
  ```

  ```python gRPC theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")
  ```
</CodeGroup>

When [creating an index](/guides/index-data/create-an-index), import the `ServerlessSpec` or `PodSpec` class as well:

<CodeGroup>
  ```Python Serverless index theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone
  from pinecone import ServerlessSpec

  pc = Pinecone(api_key="YOUR_API_KEY")

  pc.create_index(
    name="docs-example",
    dimension=1536,
    metric="cosine",
    spec=ServerlessSpec(
      cloud="aws",
      region="us-east-1"
    )
  )
  ```

  ```Python Pod-based index theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone
  from pinecone import PodSpec

  pc = Pinecone(api_key="YOUR_API_KEY")

  pc.create_index(
    name="docs-example",
    dimension=1536,
    metric="cosine",
    spec=PodSpec(
      environment="us-west-1-gcp",
      pod_type="p1.x1",
      pods=1
    )
  )
  ```
</CodeGroup>

## Proxy configuration

If your network setup requires you to interact with Pinecone through a proxy, you will need to pass additional configuration using optional keyword parameters:

* `proxy_url`: The location of your proxy. This could be an HTTP or HTTPS URL depending on your proxy setup.
* `proxy_headers`: Accepts a python dictionary which can be used to pass any custom headers required by your proxy. If your proxy is protected by authentication, use this parameter to pass basic authentication headers with a digest of your username and password. The `make_headers` utility from `urllib3` can be used to help construct the dictionary. **Note:** Not supported with Asyncio.
* `ssl_ca_certs`: By default, the client will perform SSL certificate verification using the CA bundle maintained by Mozilla in the [`certifi`](https://pypi.org/project/certifi/) package. If your proxy is using self-signed certicates, use this parameter to specify the path to the certificate (PEM format).
* `ssl_verify`: SSL verification is enabled by default, but it is disabled when set to `False`. It is not recommened to go into production with SSL verification disabled.

<CodeGroup>
  ```python HTTP theme={null}
  from pinecone import Pinecone
  import urllib3
  from urllib3.util import make_headers

  pc = Pinecone(
      api_key="YOUR_API_KEY",
      proxy_url='https://your-proxy.com',
      proxy_headers=make_headers(proxy_basic_auth='username:password'),
      ssl_ca_certs='path/to/cert-bundle.pem'
  )
  ```

  ```python gRPC theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone
  import urllib3
  from urllib3.util import make_headers

  pc = Pinecone(
      api_key="YOUR_API_KEY",
      proxy_url='https://your-proxy.com',
      proxy_headers=make_headers(proxy_basic_auth='username:password'),
      ssl_ca_certs='path/to/cert-bundle.pem'
  )
  ```

  ```python asyncio theme={null}
  import asyncio
  from pinecone import PineconeAsyncio
  	
  async def main():
      async with PineconeAsyncio(
          api_key="YOUR_API_KEY",
          proxy_url='https://your-proxy.com',
          ssl_ca_certs='path/to/cert-bundle.pem'
      ) as pc:
          # Do async things
          await pc.list_indexes()

  asyncio.run(main())
  ```
</CodeGroup>

## Async requests

Pinecone Python SDK versions 6.0.0 and later provide `async` methods for use with [asyncio](https://docs.python.org/3/library/asyncio.html). Asyncio support makes it possible to use Pinecone with modern async web frameworks such as [FastAPI](https://fastapi.tiangolo.com/), [Quart](https://quart.palletsprojects.com/en/latest/), and [Sanic](https://sanic.dev/en/), and should significantly increase the efficiency of running requests in parallel.

Use the [`PineconeAsyncio`](https://sdk.pinecone.io/python/asyncio.html) class to create and manage indexes and the [`IndexAsyncio`](https://sdk.pinecone.io/python/asyncio.html#pinecone.db_data.IndexAsyncio) class to read and write index data. To ensure that sessions are properly closed, use the `async with` syntax when creating `PineconeAsyncio` and `IndexAsyncio` objects.

<CodeGroup>
  ```python Manage indexes theme={null}
  # pip install "pinecone[asyncio]"
  import asyncio
  from pinecone import PineconeAsyncio, ServerlessSpec

  async def main():
      async with PineconeAsyncio(api_key="YOUR_API_KEY") as pc:
          if not await pc.has_index(index_name):
              desc = await pc.create_index(
                  name="docs-example",
                  dimension=1536,
                  metric="cosine",
                  spec=ServerlessSpec(
                      cloud="aws",
                      region="us-east-1"
                  ),
                  deletion_protection="disabled",
                  tags={
                      "environment": "development"
                  }
              )

  asyncio.run(main())
  ```

  ```python Read and write index data theme={null}
  # pip install "pinecone[asyncio]"
  import asyncio
  from pinecone import Pinecone

  async def main():
      pc = Pinecone(api_key="YOUR_API_KEY")
      async with pc.IndexAsyncio(host="INDEX_HOST") as idx:
          await idx.upsert_records(
              namespace="example-namespace",
              records=[
                  {
                      "id": "1",
                      "title": "The Great Gatsby",
                      "author": "F. Scott Fitzgerald",
                      "description": "The story of the mysteriously wealthy Jay Gatsby and his love for the beautiful Daisy Buchanan.",
                      "year": 1925,
                  },
                  {
                      "id": "2",
                      "title": "To Kill a Mockingbird",
                      "author": "Harper Lee",
                      "description": "A young girl comes of age in the segregated American South and witnesses her father's courageous defense of an innocent black man.",
                      "year": 1960,
                  },
                  {
                      "id": "3",
                      "title": "1984",
                      "author": "George Orwell",
                      "description": "In a dystopian future, a totalitarian regime exercises absolute control through pervasive surveillance and propaganda.",
                      "year": 1949,
                  },
              ]
          )

  asyncio.run(main())
  ```
</CodeGroup>

## Query across namespaces

Each query is limited to a single [namespace](/guides/index-data/indexing-overview#namespaces). However, the Pinecone Python SDK provides a `query_namespaces` utility method to run a query in parallel across multiple namespaces in an index and then merge the result sets into a single ranked result set with the `top_k` most relevant results.

The `query_namespaces` method accepts most of the same arguments as `query` with the addition of a required `namespaces` parameter.

<Tabs>
  <Tab title="Python SDK without gRPC">
    When using the Python SDK without gRPC extras, to get good performance, it is important to set values for the `pool_threads` and `connection_pool_maxsize` properties on the index client. The `pool_threads` setting is the number of threads available to execute requests, while `connection_pool_maxsize` is the number of cached http connections that will be held. Since these tasks are not computationally heavy and are mainly i/o bound, it should be okay to have a high ratio of threads to cpus.

    The combined results include the sum of all read unit usage used to perform the underlying queries for each namespace.

    ```python Python theme={null}
    from pinecone import Pinecone

    pc = Pinecone(api_key="YOUR_API_KEY")
    index = pc.Index(
        name="docs-example",
        pool_threads=50,             # <-- make sure to set these
        connection_pool_maxsize=50,  # <-- make sure to set these
    )

    query_vec = [ 0.1, ...] # an embedding vector with same dimension as the index
    combined_results = index.query_namespaces(
        vector=query_vec,
        namespaces=['ns1', 'ns2', 'ns3', 'ns4'],
        metric="cosine",
        top_k=10,
        include_values=False,
        include_metadata=True,
        filter={"genre": { "$eq": "comedy" }},
        show_progress=False,
    )

    for scored_vec in combined_results.matches:
        print(scored_vec)
    print(combined_results.usage)
    ```
  </Tab>

  <Tab title="Python SDK with gRPC">
    When using the Python SDK with gRPC extras, there is no need to set the `connection_pool_maxsize` because grpc makes efficient use of open connections by default.

    ```python Python theme={null}
    from pinecone.grpc import PineconeGRPC

    pc = PineconeGRPC(api_key="YOUR_API_KEY")
    index = pc.Index(
        name="docs-example",
        pool_threads=50, # <-- make sure to set this
    )

    query_vec = [ 0.1, ...] # an embedding vector with same dimension as the index
    combined_results = index.query_namespaces(
        vector=query_vec,
        namespaces=['ns1', 'ns2', 'ns3', 'ns4'],
        metric="cosine",
        top_k=10,
        include_values=False,
        include_metadata=True,
        filter={"genre": { "$eq": "comedy" }},
        show_progress=False,
    )

    for scored_vec in combined_results.matches:
        print(scored_vec)
    print(combined_results.usage)
    ```
  </Tab>
</Tabs>

## Upsert from a dataframe

To quickly ingest data when using the [Python SDK](/reference/sdks/python/overview), use the `upsert_from_dataframe` method. The method includes retry logic and`batch_size`, and is performant especially with Parquet file data sets.

The following example upserts the `uora_all-MiniLM-L6-bm25` dataset as a dataframe.

```Python Python theme={null}
from pinecone import Pinecone, ServerlessSpec
from pinecone_datasets import list_datasets, load_dataset

pc = Pinecone(api_key="API_KEY")

dataset = load_dataset("quora_all-MiniLM-L6-bm25")

pc.create_index(
  name="docs-example",
  dimension=384,
  metric="cosine",
  spec=ServerlessSpec(
    cloud="aws",
    region="us-east-1"
  )
)

# To get the unique host for an index, 
# see https://docs.pinecone.io/guides/manage-data/target-an-index
index = pc.Index(host="INDEX_HOST")

index.upsert_from_dataframe(dataset.drop(columns=["blob"]))
```


# Reference
Source: https://docs.pinecone.io/reference/sdks/python/reference

Reference documentation for the Pinecone Python SDK, including client setup, types, and methods for managing indexes and vector data operations.



# Spark-Pinecone connector
Source: https://docs.pinecone.io/reference/tools/pinecone-spark-connector

Pinecone data tools: Use the connector to efficiently create, ingest, and update vector embeddings at scale with Databricks and Pinecone.

Use the [`spark-pinecone` connector](https://github.com/pinecone-io/spark-pinecone/) to efficiently create, ingest, and update [vector embeddings](https://www.pinecone.io/learn/vector-embeddings/) at scale with [Databricks and Pinecone](/integrations/databricks).

## Install the Spark-Pinecone connector

<Tabs>
  <Tab title="Databricks platform">
    1. [Install the Spark-Pinecone connector as a library](https://docs.databricks.com/en/libraries/cluster-libraries.html#install-a-library-on-a-cluster).
    2. Configure the library as follows:
       1. Select **File path/S3** as the **Library Source**.

       2. Enter the S3 URI for the Pinecone assembly JAR file:

          ```
          s3://pinecone-jars/1.1.0/spark-pinecone-uberjar.jar  
          ```

          <Note>
            Databricks platform users must use the Pinecone assembly jar listed above to ensure that the proper dependecies are installed.
          </Note>

       3. Click **Install**.
  </Tab>

  <Tab title="Databricks on AWS">
    1. [Install the Spark-Pinecone connector as a library](https://docs.databricks.com/en/libraries/cluster-libraries.html#install-a-library-on-a-cluster).
    2. Configure the library as follows:
       1. Select **File path/S3** as the **Library Source**.

       2. Enter the S3 URI for the Pinecone assembly JAR file:

          ```
          s3://pinecone-jars/1.1.0/spark-pinecone-uberjar.jar  
          ```

       3. Click **Install**.
  </Tab>

  <Tab title="Databricks on GCP / Azure">
    1. [Install the Spark-Pinecone connector as a library](https://docs.databricks.com/en/libraries/cluster-libraries.html#install-a-library-on-a-cluster).
    2. Configure the library as follows:
       1. [Download the Pinecone assembly JAR file](https://repo1.maven.org/maven2/io/pinecone/spark-pinecone_2.12/1.1.0/).
       2. Select **Workspace** as the **Library Source**.
       3. Upload the JAR file.
       4. Click **Install**.
  </Tab>
</Tabs>

## Batch upsert

To batch upsert embeddings to Pinecone:

<CodeGroup>
  ```python Python theme={null}
  from pyspark import SparkConf
  from pyspark.sql import SparkSession
  from pyspark.sql.types import StructType, StructField, ArrayType, FloatType, StringType, LongType

  # Your API key and index name
  api_key = "PINECONE_API_KEY"
  index_name = "PINECONE_INDEX_NAME"
  source_tag = "PINECONE_SOURCE_TAG"

  COMMON_SCHEMA = StructType([
      StructField("id", StringType(), False),
      StructField("namespace", StringType(), True),
      StructField("values", ArrayType(FloatType(), False), False),
      StructField("metadata", StringType(), True),
      StructField("sparse_values", StructType([
          StructField("indices", ArrayType(LongType(), False), False),
          StructField("values", ArrayType(FloatType(), False), False)
      ]), True)
  ])

  # Initialize Spark
  spark = SparkSession.builder.getOrCreate()

  # Read the file and apply the schema
  df = spark.read \
      .option("multiLine", value = True) \
      .option("mode", "PERMISSIVE") \
      .schema(COMMON_SCHEMA) \
      .json("src/test/resources/sample.jsonl")

  # Show if the read was successful
  df.show()

  # Write the dataFrame to Pinecone in batches 
  df.write \
      .option("pinecone.apiKey", api_key) \
      .option("pinecone.indexName", index_name) \
      .option("pinecone.sourceTag", source_tag) \
      .format("io.pinecone.spark.pinecone.Pinecone") \
      .mode("append") \
      .save()
  ```

  ```scala Scala theme={null}
  import io.pinecone.spark.pinecone.{COMMON_SCHEMA, PineconeOptions}
  import org.apache.spark.SparkConf
  import org.apache.spark.sql.{SaveMode, SparkSession}

  object MainApp extends App {
    // Your API key and index name
    val apiKey = "PINECONE_API_KEY"
    val indexName = "PINECONE_INDEX_NAME"
    val sourceTag = "PINECONE_SOURCE_TAG"

    // Configure Spark to run locally with all available cores
    val conf = new SparkConf()
      .setMaster("local[*]")

    // Create a Spark session with the defined configuration
    val spark = SparkSession.builder().config(conf).getOrCreate()

    // Read the JSON file into a DataFrame, applying the COMMON_SCHEMA
    val df = spark.read
      .option("multiLine", value = true)
      .option("mode", "PERMISSIVE")
      .schema(COMMON_SCHEMA)
      .json("src/test/resources/sample.jsonl") // path to sample.jsonl

    // Define Pinecone options as a Map
    val pineconeOptions = Map(
      PineconeOptions.PINECONE_API_KEY_CONF -> apiKey,
      PineconeOptions.PINECONE_INDEX_NAME_CONF -> indexName,
      PineconeOptions.PINECONE_SOURCE_TAG_CONF -> sourceTag
    )

    // Show if the read was successful
    df.show(df.count().toInt)
    
    // Write the DataFrame to Pinecone using the defined options in batches
    df.write
      .options(pineconeOptions)
      .format("io.pinecone.spark.pinecone.Pinecone")
      .mode(SaveMode.Append)
      .save()
  }
  ```
</CodeGroup>

<Tip>
  For a guide on how to set up batch upserts, refer to the [Databricks integration page](/integrations/databricks#setup-guide).
</Tip>

## Stream upsert

To stream upsert embeddings to Pinecone:

<CodeGroup>
  ```python Python theme={null}
  from pyspark.sql import SparkSession
  from pyspark.sql.types import StructType, StructField, ArrayType, FloatType, StringType, LongType
  import os

  # Your API key and index name
  api_key = "PINECONE_API_KEY"
  index_name = "PINECONE_INDEX_NAME"
  source_tag = "PINECONE_SOURCE_TAG"

  COMMON_SCHEMA = StructType([
      StructField("id", StringType(), False),
      StructField("namespace", StringType(), True),
      StructField("values", ArrayType(FloatType(), False), False),
      StructField("metadata", StringType(), True),
      StructField("sparse_values", StructType([
          StructField("indices", ArrayType(LongType(), False), False),
          StructField("values", ArrayType(FloatType(), False), False)
      ]), True)
  ])

  # Initialize Spark session
  spark = SparkSession.builder \
      .appName("StreamUpsertExample") \
      .config("spark.sql.shuffle.partitions", 3) \
      .master("local") \
      .getOrCreate()

  # Read the stream of JSON files, applying the schema from the input directory
  lines = spark.readStream \
      .option("multiLine", True) \
      .option("mode", "PERMISSIVE") \
      .schema(COMMON_SCHEMA) \
      .json("path/to/input/directory/")

  # Write the stream to Pinecone using the defined options
  upsert = lines.writeStream \
      .format("io.pinecone.spark.pinecone.Pinecone") \
      .option("pinecone.apiKey", api_key) \
      .option("pinecone.indexName", index_name) \
      .option("pinecone.sourceTag", source_tag) \
      .option("checkpointLocation", "path/to/checkpoint/dir") \
      .outputMode("append") \
      .start()

  upsert.awaitTermination()
  ```

  ```scala Scala theme={null}
  import io.pinecone.spark.pinecone.{COMMON_SCHEMA, PineconeOptions}
  import org.apache.spark.SparkConf
  import org.apache.spark.sql.{SaveMode, SparkSession}

  object MainApp extends App {
    // Your API key and index name
    val apiKey = "PINECONE_API_KEY"
    val indexName = "PINECONE_INDEX_NAME"

    // Create a Spark session
    val spark = SparkSession.builder()
      .appName("StreamUpsertExample")
      .config("spark.sql.shuffle.partitions", 3)
      .master("local")
      .getOrCreate()

    // Read the JSON files into a DataFrame, applying the COMMON_SCHEMA from input directory
    val lines = spark.readStream
      .option("multiLine", value = true)
      .option("mode", "PERMISSIVE")
      .schema(COMMON_SCHEMA)
      .json("path/to/input/directory/")

    // Define Pinecone options as a Map
    val pineconeOptions = Map(
      PineconeOptions.PINECONE_API_KEY_CONF -> System.getenv("PINECONE_API_KEY"),
      PineconeOptions.PINECONE_INDEX_NAME_CONF -> System.getenv("PINECONE_INDEX"),
      PineconeOptions.PINECONE_SOURCE_TAG_CONF -> System.getenv("PINECONE_SOURCE_TAG")
    )

    // Write the stream to Pinecone using the defined options
    val upsert = lines
      .writeStream
      .format("io.pinecone.spark.pinecone.Pinecone")
      .options(pineconeOptions)
      .option("checkpointLocation", "path/to/checkpoint/dir")
      .outputMode("append")
      .start()

    upsert.awaitTermination()
  }
  ```
</CodeGroup>

## Learn more

* [Spark-Pinecone connector setup guide](/integrations/databricks#setup-guide)
* [GitHub](https://github.com/pinecone-io/spark-pinecone)


# Notebooks
Source: https://docs.pinecone.io/examples/notebooks

Runnable Colab notebooks covering semantic search, lexical search, hybrid search, RAG, embeddings, reranking, and data ingestion with Pinecone.

<h2>Search</h2>

<div>
  <ExampleCard title="Full-text search">
    <Tag />

    <Tag />

    <Tag />

    <Tag />
  </ExampleCard>

  <ExampleCard title="Semantic search">
    <Tag />

    <Tag icon="/images/examples/huggingface-icon.svg" />

    <Tag />
  </ExampleCard>

  <ExampleCard title="Lexical search">
    <Tag />

    <Tag />

    <Tag />
  </ExampleCard>

  <ExampleCard title="Cascading retrieval">
    <Tag />

    <Tag />

    <Tag />

    <Tag />
  </ExampleCard>

  <ExampleCard title="Reranking search results">
    <Tag />

    <Tag icon="https://cdn.sanity.io/images/vr8gru94/production/40b1d05ee1325e6d9e4886af4e76ff06d844faff-188x188.jpg" />
  </ExampleCard>
</div>

<h2>Retrieval-augmented generation (RAG)</h2>

<div>
  <ExampleCard title="RAG with hybrid search and Claude">
    <Tag />

    <Tag />

    <Tag />

    <Tag />

    <Tag />

    <Tag />
  </ExampleCard>

  <ExampleCard title="Agentic RAG with Claude">
    <Tag />

    <Tag />

    <Tag />

    <Tag />
  </ExampleCard>

  <ExampleCard title="RAG with LangChain and OpenAI">
    <Tag icon="/images/examples/openai-icon.svg" />

    <Tag icon="/images/examples/openai-icon.svg" />

    <Tag />

    <Tag />
  </ExampleCard>

  <ExampleCard title="RAG with cascading retrieval and OpenAI ">
    <Tag icon="/images/examples/openai-icon.svg" />

    <Tag />

    <Tag />

    <Tag />

    <Tag />

    <Tag />
  </ExampleCard>

  <ExampleCard title="Retrieval Agents with Pinecone Assistant, LangChain and LangGraph">
    <Tag icon="/images/examples/openai-icon.svg" />

    <Tag icon="/images/examples/openai-icon.svg" />

    <Tag />

    <Tag />

    <Tag />

    <Tag />
  </ExampleCard>
</div>

<h2>Miscellaneous</h2>

<div>
  <ExampleCard title="Import from object storage">
    <Tag />
  </ExampleCard>
</div>


# Reference architectures
Source: https://docs.pinecone.io/examples/reference-architectures

Official AWS reference architecture for building high-scale production systems with Pinecone, including Pulumi IaC, documentation, and video tutorial.

<Card title="AWS Reference Architecture" icon="text-size">
  <br />

  The official AWS Reference Architecture for high-scale systems using Pinecone.

  <br />

  <a href="#">
    [Documentation](https://github.com/pinecone-io/aws-reference-architecture-pulumi/blob/main/README.md)
  </a>

  <a href="#">
    [Video tutorial](https://youtu.be/ySznARngHts)
  </a>

  <a href="#">
    [Source code](https://github.com/pinecone-io/aws-reference-architecture-pulumi)
  </a>
</Card>


# Sample apps
Source: https://docs.pinecone.io/examples/sample-apps

Full-stack sample applications built with Pinecone: semantic search over PDFs, multi-tenant RAG with namespace isolation, multimodal search, and Assistant chat.

<div>
  <div>
    <ExampleCard title="Semantic search">
      <Tag icon="/images/examples/nextjs.svg" />

      <Tag icon="/images/examples/openai-icon.svg" />
    </ExampleCard>

    <ExampleCard title="Multi-tenant RAG">
      <Tag icon="/images/examples/nextjs.svg" />

      <Tag icon="/images/examples/openai-icon.svg" />
    </ExampleCard>

    <ExampleCard title="Multimodal search">
      <Tag icon="/images/examples/nextjs.svg" />

      <Tag icon="/images/google-cloud-vertex-ai.svg" />
    </ExampleCard>

    <ExampleCard title="Pinecone Assistant">
      <Tag icon="/images/examples/nextjs.svg" />
    </ExampleCard>
  </div>

  <h2>More code examples</h2>

  <div>
    <UtilityExampleCard title="Combine full-text search with dense vector ranking" />

    <UtilityExampleCard title="Use the Python SDK with FastAPI" />

    <UtilityExampleCard title="Implement semantic search with TypeScript" />

    <UtilityExampleCard title="Build an article recommender with TypeScript" />

    <UtilityExampleCard title="Create a chatbot agent with LangChain" />

    <UtilityExampleCard title="Implement image search with TypeScript" />
  </div>
</div>


# Agent Skills
Source: https://docs.pinecone.io/integrations/agent-skills

Install the Pinecone Agent Skills library in any agentic IDE to manage indexes, run semantic search, and build RAG assistants with natural language.

Pinecone's official [Agent Skills](https://github.com/pinecone-io/skills) library brings Pinecone capabilities to any agentic IDE that supports the Agent Skills standard. Use skills to manage indexes, run semantic search, create document Q\&A assistants, and more — all through natural language in your IDE.

Compatible with [GitHub Copilot](https://github.com/features/copilot), [Codex](https://chatgpt.com/codex), and other agentic IDEs.

<PrimarySecondaryCTA />

<Tip>
  If you use **Claude Code**, install the dedicated [Pinecone plugin for Claude Code](/integrations/claude-code) instead. If you use **Gemini CLI**, install the dedicated [Pinecone extension for Gemini CLI](/integrations/gemini-cli) instead. If you use **Cursor**, install the dedicated [Pinecone plugin for Cursor](/integrations/cursor) instead. Each includes additional features specific to that tool.
</Tip>

## Features

* **Built-in skills** for index management, semantic search, full-text search, assistant creation, and more
* **Universal compatibility** with any IDE that supports Agent Skills
* **Works with the Pinecone MCP server** for direct index operations

## Prerequisites

* A [Pinecone API key](https://app.pinecone.io/organizations/-/keys)
* [Node.js](https://nodejs.org/) installed (for `npx`)
* [Pinecone MCP server](/guides/operations/mcp-server) configured in your IDE (optional, enables the `query` skill)
* [uv](https://docs.astral.sh/uv/getting-started/installation/) installed (optional, runs bundled Python scripts)
* [Pinecone CLI](/reference/cli/quickstart) installed (optional, enables the `cli` skill)

## Installation

<Steps>
  <Step title="Set your API key">
    ```shell theme={null}
    export PINECONE_API_KEY="YOUR_API_KEY"
    ```

    Replace `YOUR_API_KEY` with your [Pinecone API key](https://app.pinecone.io/organizations/-/keys).
  </Step>

  <Step title="Install the skills">
    ```shell theme={null}
    npx skills add pinecone-io/skills
    ```

    This downloads Pinecone's skills into your project, making them available to your IDE's AI agent.
  </Step>

  <Step title="Configure the MCP server (optional)">
    For full functionality, configure the [Pinecone MCP server](/guides/operations/mcp-server) in your IDE. This enables the `query` skill and direct index operations.
  </Step>
</Steps>

## Available skills

| Skill                | Description                                                                                                                                                     |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **quickstart**       | Step-by-step onboarding — create an index, upload data, and run your first search.                                                                              |
| **query**            | Search integrated indexes using natural language text via the Pinecone MCP.                                                                                     |
| **assistant**        | Create, manage, and chat with Pinecone Assistants for document Q\&A with citations.                                                                             |
| **cli**              | Use the Pinecone CLI for terminal-based index and vector management across all index types.                                                                     |
| **full-text-search** | Create, ingest into, and query a Pinecone full-text-search (FTS) index using the preview API.                                                                   |
| **n8n**              | Build [n8n](/integrations/n8n) workflows with the Pinecone Assistant node or Pinecone Vector Store, including best practices and full workflow JSON generation. |
| **mcp**              | Reference for all available Pinecone MCP server tools and their parameters.                                                                                     |
| **pinecone-docs**    | Curated links to official Pinecone documentation, organized by topic.                                                                                           |
| **help**             | Overview of all skills and what you need to get started.                                                                                                        |

## MCP tools

Agent Skills work alongside the [Pinecone MCP server](/guides/operations/mcp-server), which provides tools for listing indexes, creating indexes, upserting records, searching, reranking, and more. Configure the MCP server in your IDE to enable the `query` skill and direct index operations.

For the full list of MCP tools, see [Use the Pinecone MCP server](/guides/operations/mcp-server).

## Resources

* [GitHub repository](https://github.com/pinecone-io/skills)
* [Pinecone MCP server guide](/guides/operations/mcp-server)


# Airbyte
Source: https://docs.pinecone.io/integrations/airbyte

Use the Airbyte Pinecone destination connector to build no-code ETL pipelines that embed source data and upsert vectors for semantic search and RAG.

Airbyte offers a platform for creating ETL pipelines without writing integration code. It supports integrations with hundreds of systems, including databases, data warehouses, and SaaS products.

The Pinecone connector for Airbyte allows users to connect these systems directly into Pinecone. The connector fetches data from the connected source, embeds the data using an large language model (LLM), and then upserts it into Pinecone. From enhancing semantic search capabilities to building intelligent recommendation systems, the Pinecone Airbyte connector offers a versatile solution. By tapping into Airbyte's extensive array of source connectors, you can explore new ways to enrich your data-driven projects and achieve your specific goals.

<PrimarySecondaryCTA />

## Related articles

* [Data Sync and Search: Pinecone and Airbyte](https://www.pinecone.io/learn/series/airbyte/)
* [Introduction to Airbyte and the Pinecone connector](https://www.pinecone.io/learn/series/airbyte/airbyte-and-pinecone-intro/)
* [Postgres to Pinecone Syncing](https://www.pinecone.io/learn/series/airbyte/airbyte-postgres-to-pinecone/)


# Apify
Source: https://docs.pinecone.io/integrations/apify

Use the Apify Pinecone integration to crawl and scrape websites, embed the results, and upsert vectors for RAG and semantic search over web content.

[Apify](https://apify.com) is a web scraping and data extraction platform. It provides an app store with more than a thousand ready-made cloud tools called Actors. These tools are suitable for use cases including extracting structured data from e-commerce sites, social media, search engines, online maps, or any other website.

For example, the [Website Content Crawler](https://apify.com/apify/website-content-crawler) Actor can deeply crawl websites, clean their HTML by removing a cookies modal, footer, or navigation, and then transform the HTML into Markdown. This Markdown can then be used as training data for AI models or to feed LLM and generative AI applications with web content.

The Apify integration for Pinecone makes it easy to transfer results from Actors to the Pinecone vector database, enabling Retrieval-Augmented Generation (RAG) or semantic search over data extracted from the web.

<PrimarySecondaryCTA />


# Aryn
Source: https://docs.pinecone.io/integrations/aryn

Use Aryn Sycamore and the Partitioning Service with Pinecone to extract, chunk, and embed complex PDFs and documents for higher-accuracy RAG pipelines.

Aryn is an AI-powered ETL system for complex, unstructured documents like PDFs, HTML, presentations, and more. It's purpose-built for building RAG and GenAI applications, providing up to 6x better accuracy in chunking and extracting information from documents. This can lead to 30% better recall and 2x improvement in answer accuracy for real-world use cases.

Aryn's ETL system has two components: Sycamore and the Aryn Partitioning Service. Sycamore is Aryn's open source document processing engine, available as a Python library. It contains a set of transforms for information extraction, LLM-powered enrichment, data cleaning, creating vector embeddings, and loading Pinecone indexes.

The Aryn Partitioning Service is used as a first step in a Sycamore data processing pipeline, and it identifies and extracts parts of documents, like text, tables, images, and more. It uses a state-of-the-art vision segmentation AI model, trained on hundreds of thousands of human-annotated documents.

The Pinecone integration with Aryn enables developers to easily chunk documents, create vector embeddings, and load Pinecone with high-quality data.

<PrimarySecondaryCTA />


# Box
Source: https://docs.pinecone.io/integrations/box

Connect Box folders to Pinecone Database to embed documents with Pinecone Inference and build RAG agents and semantic search over Box content.

Connect a [Box](https://www.box.com/) account to a Pinecone vector database.

This integration allows embeddings generation based on content stored in a particular account and folder in Box. By default, the Pinecone Inference API is used, as well as OpenAI for the LLM. The integration can be used within a larger AI agent or workflow.

<PrimarySecondaryCTA />


# Claude Code Plugin
Source: https://docs.pinecone.io/integrations/claude-code

Install the official Pinecone plugin for Claude Code to manage indexes, run vector search, and build RAG assistants from the terminal with slash commands.

The official Pinecone plugin for [Claude Code](https://claude.ai/code) provides AI-powered skills, MCP server integration, and slash commands directly in your terminal. Use natural language to manage indexes, query data, build RAG applications, and create document Q\&A assistants — all with up-to-date Pinecone API knowledge.

<PrimarySecondaryCTA />

## Features

* **Built-in skills** for index management, semantic search, full-text search, assistant creation, and more
* **MCP server integration** for direct Pinecone operations from Claude Code
* **Slash commands** like `/pinecone:quickstart` and `/pinecone:query` for quick access
* **Natural language recognition** — assistant commands work without explicit slash commands

## Prerequisites

* A [Pinecone API key](https://app.pinecone.io/organizations/-/keys)
* [Node.js](https://nodejs.org/) installed (`npx` must be on your `PATH`)
* [uv](https://docs.astral.sh/uv/getting-started/installation/) installed (required for assistant commands)
* [Pinecone CLI](/reference/cli/quickstart) installed (optional, for advanced operations)

## Installation

<Steps>
  <Step title="Set your API key">
    ```shell theme={null}
    export PINECONE_API_KEY="YOUR_API_KEY"
    ```

    Replace `YOUR_API_KEY` with your [Pinecone API key](https://app.pinecone.io/organizations/-/keys).
  </Step>

  <Step title="Install the plugin">
    From your terminal:

    ```shell theme={null}
    claude plugin install pinecone
    ```

    Or from within Claude Code:

    ```text theme={null}
    /plugin install pinecone
    ```
  </Step>

  <Step title="Restart Claude Code">
    Restart Claude Code to activate the plugin. Then run `/pinecone:help` to verify the installation.
  </Step>
</Steps>

## Available skills

| Skill                | Command                      | Description                                                                                                                                                     |
| -------------------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Help**             | `/pinecone:help`             | Overview of all skills and setup requirements.                                                                                                                  |
| **Quickstart**       | `/pinecone:quickstart`       | Interactive onboarding — create an index, upsert data, and query.                                                                                               |
| **Query**            | `/pinecone:query`            | Search integrated indexes using natural language.                                                                                                               |
| **Assistant**        | `/pinecone:assistant`        | Create, upload, sync, and chat with Pinecone Assistants.                                                                                                        |
| **CLI**              | `/pinecone:cli`              | Guide for using the Pinecone CLI from the terminal.                                                                                                             |
| **Full-text search** | `/pinecone:full-text-search` | Create, ingest into, and query a Pinecone full-text-search (FTS) index using the preview API.                                                                   |
| **n8n**              | `/pinecone:n8n`              | Build [n8n](/integrations/n8n) workflows with the Pinecone Assistant node or Pinecone Vector Store, including best practices and full workflow JSON generation. |
| **MCP**              | `/pinecone:mcp`              | Reference for all Pinecone MCP server tools.                                                                                                                    |
| **Docs**             | `/pinecone:docs`             | Curated links to official Pinecone documentation.                                                                                                               |

## MCP tools

The plugin includes the Pinecone MCP server, which provides the following tools:

* `search-docs` — Search the official Pinecone documentation.
* `list-indexes` — List all available Pinecone indexes.
* `describe-index` — Get index configuration and namespaces.
* `describe-index-stats` — Get record counts and namespace statistics.
* `create-index-for-model` — Create a new index with integrated embeddings.
* `upsert-records` — Insert or update records in an index.
* `search-records` — Search records with optional metadata filtering and reranking.
* `cascading-search` — Search across multiple indexes with deduplication and reranking.
* `rerank-documents` — Rerank documents using a specified reranking model.

For full MCP server documentation, see [Use the Pinecone MCP server](/guides/operations/mcp-server).

## Resources

* [GitHub repository](https://github.com/pinecone-io/pinecone-claude-code-plugin)
* [Pinecone MCP server guide](/guides/operations/mcp-server)
* [Claude Code documentation](https://docs.claude.com/en/docs/claude-code/quickstart)


# Confluent
Source: https://docs.pinecone.io/integrations/confluent

Use the Pinecone Sink Connector for Confluent Kafka to stream events, embed them with LLMs, and upsert vectors for real-time semantic search and RAG.

Confluent allows you to connect and process all of your data in real time with a cloud-native and complete data streaming platform available everywhere you need it. Confluent's Kafka Connect is a tool for scalably and reliably streaming data between Apache Kafka and other data systems. It makes it simple to quickly define connectors that move large data sets in and out of Kafka.

Use the Pinecone Sink Connector, a Kafka Connect plugin for Pinecone, to take content from Confluent Cloud, convert it into vector embeddings using large language models (LLMs), and then store these embeddings in a Pinecone vector database.

<PrimarySecondaryCTA />


# Cursor Plugin
Source: https://docs.pinecone.io/integrations/cursor

Install the official Pinecone plugin for Cursor to manage indexes, run vector search, and build RAG apps from the editor using MCP and slash commands.

The official Pinecone plugin for [Cursor](https://www.cursor.com/) provides AI-powered skills, MCP server integration, and slash commands directly in your editor. Use natural language to manage indexes, query data, build RAG applications, and create document Q\&A assistants — all with up-to-date Pinecone API knowledge.

<PrimarySecondaryCTA />

## Features

* **Built-in skills** for index management, semantic search, full-text search, assistant creation, and more
* **Bundled MCP server** (`@pinecone-database/mcp`) for direct Pinecone operations from Cursor Agent
* **Slash commands** like `/pinecone-quickstart` and `/pinecone-query` for quick access
* **Natural language activation** — Cursor Agent invokes the right skill automatically based on your conversation

## Prerequisites

* A [Pinecone API key](https://app.pinecone.io/organizations/-/keys)
* [Cursor](https://www.cursor.com/) installed
* [Node.js](https://nodejs.org/) v18+ (required for the bundled MCP server)
* [uv](https://docs.astral.sh/uv/getting-started/installation/) installed (optional, runs bundled Python scripts)
* [Pinecone CLI](/reference/cli/quickstart) installed (optional, enables the `pinecone-cli` skill)

## Installation

<Steps>
  <Step title="Set your API key">
    Add your [Pinecone API key](https://app.pinecone.io/organizations/-/keys) to a `.env` file at your workspace root:

    ```text theme={null}
    PINECONE_API_KEY=your-key
    ```

    Cursor loads this file into the MCP server via its [`envFile`](https://cursor.com/docs/mcp) field, so you don't need to export the key in your shell.
  </Step>

  <Step title="Install the plugin">
    In Cursor chat, run:

    ```text theme={null}
    /add-plugin pinecone
    ```

    Or install directly from the [Cursor Marketplace](https://cursor.com/marketplace/pinecone).
  </Step>

  <Step title="Verify the installation">
    Open Cursor Agent chat and run `/pinecone-help` to confirm the skills are loaded. You can also check:

    * **Skills:** Cursor Settings > Rules — listed under "Agent Decides"
    * **MCP server:** Cursor Settings > Features > Model Context Protocol
  </Step>
</Steps>

## Available skills

| Skill                | Command                      | Description                                                                                                                                                     |
| -------------------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Help**             | `/pinecone-help`             | Overview of all skills and setup requirements.                                                                                                                  |
| **Quickstart**       | `/pinecone-quickstart`       | Interactive onboarding — create an index, upsert data, and query. Choose between a Database path or Assistant path.                                             |
| **Query**            | `/pinecone-query`            | Search integrated indexes using natural language via the Pinecone MCP server.                                                                                   |
| **Assistant**        | `/pinecone-assistant`        | Create, upload, sync, and chat with Pinecone Assistants for document Q\&A with citations.                                                                       |
| **CLI**              | `/pinecone-cli`              | Guide for using the Pinecone CLI (`pc`) from the terminal.                                                                                                      |
| **Full-text search** | `/pinecone-full-text-search` | Create, ingest into, and query a Pinecone full-text-search (FTS) index using the preview API.                                                                   |
| **n8n**              | `/pinecone-n8n`              | Build [n8n](/integrations/n8n) workflows with the Pinecone Assistant node or Pinecone Vector Store, including best practices and full workflow JSON generation. |
| **MCP**              | `/pinecone-mcp`              | Reference for all Pinecone MCP server tools.                                                                                                                    |
| **Docs**             | `/pinecone-docs`             | Curated links to official Pinecone documentation.                                                                                                               |

## MCP tools

The plugin includes the Pinecone MCP server, which provides the following tools:

* `search-docs` — Search the official Pinecone documentation.
* `list-indexes` — List all available Pinecone indexes.
* `describe-index` — Get index configuration and namespaces.
* `describe-index-stats` — Get record counts and namespace statistics.
* `create-index-for-model` — Create a new index with integrated embeddings.
* `upsert-records` — Insert or update records in an index.
* `search-records` — Search records with optional metadata filtering and reranking.
* `cascading-search` — Search across multiple indexes with deduplication and reranking.
* `rerank-documents` — Rerank documents using a specified reranking model.

For full MCP server documentation, see [Use the Pinecone MCP server](/guides/operations/mcp-server).

## Resources

* [GitHub repository](https://github.com/pinecone-io/pinecone-cursor-plugin)
* [Cursor Marketplace listing](https://cursor.com/marketplace/pinecone)
* [Pinecone MCP server guide](/guides/operations/mcp-server)
* [Cursor documentation](https://cursor.com/docs)


# Databricks
Source: https://docs.pinecone.io/integrations/databricks

Use Databricks and the Pinecone Spark connector to distribute embedding jobs across a cluster and upsert vectors at scale for semantic search and RAG.

Databricks is a Unified Analytics Platform on top of Apache Spark. The primary advantage of using Spark is its ability to distribute workloads across a cluster of machines. By adding more machines or increasing the number of cores on each machine, it is easy to horizontally scale a cluster to handle computationally intensive tasks like vector embedding, where parallelization can save many hours of precious computation time and resources. Leveraging GPUs with Spark can produce even better results — enjoying the benefits of the fast computation of a GPU combined with parallelization will ensure optimal performance.

Efficiently create, ingest, and update vector embeddings at scale with Databricks and Pinecone.

<PrimarySecondaryCTA />

## Setup guide

In this guide, you'll create embeddings based on the [sentence-transformers/all-MiniLM-L6-v2](https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2) model from [Hugging Face](https://huggingface.co/), but the approach demonstrated here should work with any other model and dataset.

### Before you begin

Ensure you have the following:

* A [Databricks cluster](https://docs.databricks.com/en/compute/configure.html)
* A [Pinecone account](https://app.pinecone.io/)
* A [Pinecone API key](/guides/projects/understanding-projects#api-keys)

### 1. Install the Spark-Pinecone connector

<Tabs>
  <Tab title="Databricks platform">
    1. [Install the Spark-Pinecone connector as a library](https://docs.databricks.com/en/libraries/cluster-libraries.html#install-a-library-on-a-cluster).
    2. Configure the library as follows:
       1. Select **File path/S3** as the **Library Source**.

       2. Enter the S3 URI for the Pinecone assembly JAR file:

          ```
          s3://pinecone-jars/1.1.0/spark-pinecone-uberjar.jar  
          ```

          <Note>
            Databricks platform users must use the Pinecone assembly jar listed above to ensure that the proper dependecies are installed.
          </Note>

       3. Click **Install**.
  </Tab>

  <Tab title="Databricks on AWS">
    1. [Install the Spark-Pinecone connector as a library](https://docs.databricks.com/en/libraries/cluster-libraries.html#install-a-library-on-a-cluster).
    2. Configure the library as follows:
       1. Select **File path/S3** as the **Library Source**.

       2. Enter the S3 URI for the Pinecone assembly JAR file:

          ```
          s3://pinecone-jars/1.1.0/spark-pinecone-uberjar.jar  
          ```

       3. Click **Install**.
  </Tab>

  <Tab title="Databricks on GCP / Azure">
    1. [Install the Spark-Pinecone connector as a library](https://docs.databricks.com/en/libraries/cluster-libraries.html#install-a-library-on-a-cluster).
    2. Configure the library as follows:
       1. [Download the Pinecone assembly JAR file](https://repo1.maven.org/maven2/io/pinecone/spark-pinecone_2.12/1.1.0/).
       2. Select **Workspace** as the **Library Source**.
       3. Upload the JAR file.
       4. Click **Install**.
  </Tab>
</Tabs>

### 2. Load the dataset into partitions

As your example dataset, use a collection of news articles from Hugging Face's datasets library:

1. [Create a new notebook](https://docs.databricks.com/en/notebooks/notebooks-manage.html#create-a-notebook) attached to your cluster.

2. Install dependencies:

   ```
   pip install datasets transformers pinecone torch  
   ```

3. Load the dataset:

   ```Python Python theme={null}
   from datasets import list_datasets, load_dataset  
   dataset_name = "allenai/multinews_sparse_max"  
   dataset = load_dataset(dataset_name, split="train")  
   ```

4. Convert the dataset from the Hugging Face format and repartition it:

   ```Python Python theme={null}
   dataset.to_parquet("/dbfs/tmp/dataset_parquet.pq")  
   num_workers = 10  
   dataset_df = spark.read.parquet("/tmp/dataset_parquet.pq").repartition(num_workers)  
   ```

   Once the repartition is complete, you get back a DataFrame, which is a distributed collection of the data organized into named columns. It is conceptually equivalent to a table in a relational database or a dataframe in R/Python, but with richer optimizations under the hood. As mentioned above, each partition in the dataframe has an equal amount of the original data.

5. The dataset doesn't have identifiers associated with each document, so add them:

   ```Python Python theme={null}
   from pyspark.sql.types import StringType  
   from pyspark.sql.functions import monotonically_increasing_id  
   dataset_df = dataset_df.withColumn("id", monotonically_increasing_id().cast(StringType()))  
   ```

   As its name suggests, `withColumn` adds a column to the dataframe, containing a simple increasing identifier that you cast to a string.

### 3. Create the vector embeddings

1. Create a UDF (User-Defined Function) to create the embeddings, using the AutoTokenizer and AutoModel classes from the Hugging Face transformers library:

   ```Python Python theme={null}
   from transformers import AutoTokenizer, AutoModel  
   def create_embeddings(partitionData):  
       tokenizer = AutoTokenizer.from_pretrained("sentence-transformers/all-MiniLM-L6-v2")  
       model = AutoModel.from_pretrained("sentence-transformers/all-MiniLM-L6-v2")  
       for row in partitionData:  
           document = str(row.document)  
           inputs = tokenizer(document, padding=True, truncation=True, return_tensors="pt", max_length=512)  
           result = model(**inputs)  
           embeddings = result.last_hidden_state[:, 0, :].cpu().detach().numpy()  
       lst = embeddings.flatten().tolist()  
       yield [row.id, lst, "", "{}", None]  
   ```

2. Apply the UDF to the data:

   ```Python Python theme={null}
   embeddings = dataset_df.rdd.mapPartitions(create_embeddings)  
   ```

   A dataframe in Spark is a higher-level abstraction built on top of a more fundamental building block called a resilient distributed dataset (RDD). Here, you use the `mapPartitions` function, which provides finer control over the execution of the UDF by explicitly applying it to each partition of the RDD.

3. Convert the resulting RDD back into a dataframe with the schema required by Pinecone:

   ```Python Python theme={null}
   from pyspark.sql.types import StructType, StructField, StringType, ArrayType, FloatType, IntegerType  
   schema = StructType([  
       StructField("id",StringType(),True),  
       StructField("values",ArrayType(FloatType()),True),  
       StructField("namespace",StringType(),True),  
       StructField("metadata", StringType(), True),  
       StructField("sparse_values", StructType([  
           StructField("indices", ArrayType(LongType(), False), False),  
           StructField("values", ArrayType(FloatType(), False), False)  
       ]), True)  
   ])  
   embeddings_df = spark.createDataFrame(data=embeddings,schema=schema)  
   ```

### 4. Save the embeddings in Pinecone

1. Initialize the connection to Pinecone:

   ```Python Python theme={null}
   from pinecone.grpc import PineconeGRPC as Pinecone
   from pinecone import ServerlessSpec

   pc = Pinecone(api_key="YOUR_API_KEY")
   ```

2. Create an index for your embeddings:

   ```Python Python theme={null}
   pc.create_index(
   name="news",
   dimension=1536,
   metric="cosine",
   spec=ServerlessSpec(
       cloud="aws",
       region="us-east-1"
   )
   )
   ```

3. Use the Spark-Pinecone connector to save the embeddings to your index:

   ```Python Python theme={null}
   (  
       embeddings_df.write  
       .option("pinecone.apiKey", api_key) 
       .option("pinecone.indexName", index_name)  
       .format("io.pinecone.spark.pinecone.Pinecone")  
       .mode("append")  
       .save()  
   )  
   ```

   The process of writing the embeddings to Pinecone should take approximately 15 seconds. When it completes, you'll see the following:

   ```
   spark: org.apache.spark.sql.SparkSession = org.apache.spark.sql.SparkSession@41638051  
   pineconeOptions: scala.collection.immutable.Map[String,String] = Map(pinecone.apiKey -><YOUR API KEY>, pinecone.indexName -> "news")  
   ```

   This means the process was completed successfully and the embeddings have been stored in Pinecone.

4. Perform a similarity search using the embeddings you loaded into Pinecone by providing a set of vector values or a vector ID. The [query endpoint](/reference/api/2025-10/data-plane/query) will return the IDs of the most similar records in the index, along with their similarity scores:
   ```Python Python theme={null}
       index.query(
           namespace="example-namespace",
           vector=[0.3, 0.3, 0.3, 0.3, 0.3],
           top_k=3,
           include_values=True
       )
   ```
   <Note>
     If you want to make a query with a text string (e.g., `"Summarize this article"`), use the [`search` endpoint via integrated inference](/reference/api/2025-10/data-plane/search_records).
   </Note>


# Datavolo
Source: https://docs.pinecone.io/integrations/datavolo

Use Datavolo pipelines to source, transform, and enrich unstructured data into Pinecone for retrieval augmented generation and multimodal AI apps.

[Datavolo](https://datavolo.io/) helps data teams build multimodal data pipelines to support their AI initiatives. Every organization has their own private data that they need to incorporate into their AI apps, and a predominant pattern to do so has emerged: retrieval augmented generation (RAG).

Datavolo sources, transforms, and enriches data in a continuous, composable and customizable manner, landing the data in Pinecone for retrieval. This ensures organizations can securely access their unstructured data.

<PrimarySecondaryCTA />


# Estuary
Source: https://docs.pinecone.io/integrations/estuary

Use the Estuary Pinecone connector to build real-time, millisecond-latency pipelines that incrementally embed source data for LLM search and RAG.

[Estuary](https://estuary.dev/) builds real-time data pipelines that focus on moving data from sources to destinations with millisecond latency. It supports integrations with hundreds of systems including databases, warehouses, SaaS products and streaming solutions.

The Pinecone connector for Estuary enables users to source from these systems and push data to Pinecone, for an always up-to-date view. It incrementally updates source data to ensure that minimal credits are used when reaching out to get embeddings from providers prior to pushing them to Pinecone.

Estuary's Pinecone connector enables a variety of use cases like enabling LLM-based search across your organizations data and building intelligent recommendation systems. It can be set up in 5 minutes, without any engineering effort to maximize efficiency.

<PrimarySecondaryCTA />


# Fleak
Source: https://docs.pinecone.io/integrations/fleak

Use Fleak's low-code workflows with Pinecone to combine SQL, LLM inference, and vector search in serverless APIs for RAG and data enrichment pipelines.

Fleak simplifies the process of building, deploying, and managing data workflows. As a low-code platform, Fleak lets users create and deploy complex workflows using SQL and pre-configured processing nodes. The platform facilitates seamless data processing, microservice interactions, and the inference of large language models (LLMs) within a single, intuitive environment. Fleak makes advanced technology accessible and manageable for Pinecone users without requiring extensive coding hours or infrastructure knowledge.

The platform provides serverless, autoscaling HTTP API endpoints, ensuring that workflows are robust, reliable, and scalable to meet the complex data needs of enterprises. This setup allows businesses to automate and enhance their operations, driving productivity and innovation through powerful, user-friendly tools.

By integrating Pinecone into Fleak's platform, users can access and leverage their vector data to enrich their workflows without additional engineering overhead, enabling seamless data-driven decision-making, advanced analytics, and the integration of AI-driven insights.

<PrimarySecondaryCTA />


# FlowiseAI
Source: https://docs.pinecone.io/integrations/flowise

Use FlowiseAI with Pinecone to build low-code LLM apps that upsert documents and query vector indexes for RAG chatbots and semantic search flows.

Flowise is a low-code LLM apps development platform. It supports integrations with dozens of systems, including databases and chat models.

The Pinecone integration with Flowise allows users to build RAG apps, including upserting and querying documents.

<PrimarySecondaryCTA />


# Gathr
Source: https://docs.pinecone.io/integrations/gathr

Use Gathr's no-code data-to-outcome platform with Pinecone to build enterprise RAG apps, chatbots, and vector pipelines from ingestion through deployment.

[Gathr](https://www.gathr.one/) is the world's first and only "data to outcome" platform. Leading enterprises use Gathr to build and operationalize data and AI-driven solutions at scale.

Gathr unifies data engineering, machine learning, generative AI, actionable analytics, and process automation on a single platform. With Gen AI capabilities and no-code rapid application development, Gathr significantly boosts productivity for all. The unified experience fosters seamless handoff and collaboration between teams, accelerating the journey from prototype to production.

Users have achieved success with Gathr, from ingesting petabyte-scale data in real time to orchestrating thousands of complex data processing pipelines in months and delivering actionable insights and xOps solutions to multiply business impact. Additionally, Gathr helps enterprises architect Gen AI solutions for use cases like document summarization, sentiment analysis, next best action, insider threat detection, predictive maintenance, custom chatbots, and more.

Gathr Gen AI Fabric is designed to build enterprise-grade Gen AI solutions end-to-end on a unified platform. It offers production-ready building blocks for creating Gen AI solutions, out-of-the-box Gen AI solution templates, and GathrIQ, a data-to-outcome copilot.

One of the building blocks is integration with Vector DB and Knowledge Graphs. Gathr supports reading and writing from Pinecone using a built-in, ready-to-use connector to support use cases requiring knowledge graphs.

<PrimarySecondaryCTA />


# Gemini CLI Extension
Source: https://docs.pinecone.io/integrations/gemini-cli

Install the official Pinecone extension for Gemini CLI to manage indexes, run vector search, and build RAG assistants with natural-language commands.

The official Pinecone extension for [Gemini CLI](https://github.com/google-gemini/gemini-cli) provides AI-powered skills and MCP server integration directly in your terminal. Use natural language to manage indexes, query data, build RAG applications, and create document Q\&A assistants.

<PrimarySecondaryCTA />

## Features

* **7 built-in skills** for index management, semantic search, assistant creation, and more
* **MCP server integration** for direct Pinecone operations from Gemini CLI
* **Natural language activation** — just describe what you want and the right skill is invoked automatically

## Prerequisites

* A [Pinecone API key](https://app.pinecone.io/organizations/-/keys)
* [Gemini CLI](https://github.com/google-gemini/gemini-cli) installed
* [uv](https://docs.astral.sh/uv/getting-started/installation/) installed (required for skill scripts)
* [Pinecone CLI](/reference/cli/quickstart) installed (optional, for advanced operations)

## Installation

<Steps>
  <Step title="Set your API key">
    ```shell theme={null}
    export PINECONE_API_KEY="YOUR_API_KEY"
    ```

    Replace `YOUR_API_KEY` with your [Pinecone API key](https://app.pinecone.io/organizations/-/keys).
  </Step>

  <Step title="Install the extension">
    ```shell theme={null}
    gemini extensions install https://github.com/pinecone-io/gemini-cli-extension
    ```
  </Step>

  <Step title="Restart Gemini CLI">
    Restart Gemini CLI to activate the extension. Then ask:

    ```text theme={null}
    Use the help skill to show me what Pinecone skills are available.
    ```
  </Step>
</Steps>

<Note>
  If you hit API key errors, exit Gemini CLI, run `export PINECONE_API_KEY="your-key"` in your terminal, and start Gemini CLI again. The CLI only reads environment variables at launch.
</Note>

## Available skills

| Skill             | Description                                                                         |
| ----------------- | ----------------------------------------------------------------------------------- |
| **quickstart**    | Step-by-step onboarding — create an index, upload data, and run your first search.  |
| **query**         | Search integrated indexes using natural language text via the Pinecone MCP.         |
| **assistant**     | Create, manage, and chat with Pinecone Assistants for document Q\&A with citations. |
| **cli**           | Guide for using the Pinecone CLI from the terminal.                                 |
| **mcp**           | Reference for all available Pinecone MCP server tools and their parameters.         |
| **pinecone-docs** | Curated links to official Pinecone documentation, organized by topic.               |
| **help**          | Overview of all skills and what you need to get started.                            |

Skills are activated automatically based on your conversation. If the agent doesn't pick up a specific skill, explicitly ask for it: *"Use the quickstart skill to help me get started."*

## MCP tools

The extension includes the Pinecone MCP server, which provides the following tools:

* `search-docs` — Search the official Pinecone documentation.
* `list-indexes` — List all available Pinecone indexes.
* `describe-index` — Get index configuration and namespaces.
* `describe-index-stats` — Get record counts and namespace statistics.
* `create-index-for-model` — Create a new index with integrated embeddings.
* `upsert-records` — Insert or update records in an index.
* `search-records` — Search records with optional metadata filtering and reranking.
* `cascading-search` — Search across multiple indexes with deduplication and reranking.
* `rerank-documents` — Rerank documents using a specified reranking model.

For full MCP server documentation, see [Use the Pinecone MCP server](/guides/operations/mcp-server).

## Resources

* [GitHub repository](https://github.com/pinecone-io/gemini-cli-extension)
* [Pinecone MCP server guide](/guides/operations/mcp-server)
* [Gemini CLI documentation](https://github.com/google-gemini/gemini-cli)


# Integrations
Source: https://docs.pinecone.io/integrations/overview

Browse Pinecone integrations across vector embedding providers, data ingestion tools, frameworks, and infrastructure to ship AI apps faster.

<CardGroup>
  <Card href="/integrations/agent-skills">
    <span>IDEs & CLIs</span>
    <h2>Agent Skills</h2>
    <p>Universal Pinecone skills library for GitHub Copilot, Codex, and other agentic IDEs.</p>
  </Card>

  <Card href="/integrations/cursor">
    <span>IDEs & CLIs</span>
    <h2>Cursor Plugin</h2>
    <p>Official Pinecone plugin for Cursor with skills, MCP tools, and slash commands.</p>
  </Card>

  <Card href="/integrations/ai-engine">
    <div>
      <img />
    </div>

    <span>Frameworks</span>
    <h2>AI Engine</h2>
    <p>Create intelligent chatbots, generate content, build AI forms, and automate tasks — all from your WordPress dashboard.</p>
  </Card>

  <Card href="/integrations/airbyte">
    <div>
      <img />
    </div>

    <span>Data Sources</span>
    <h2>Airbyte</h2>
    <p>Seamlessly integrate, transform, and load data into Pinecone from hundreds of systems, including databases, data warehouses, and SaasS products.</p>
  </Card>

  <Card href="/integrations/amazon-bedrock">
    <div>
      <BedrockIcon />
    </div>

    <span>Frameworks</span>
    <h2>Amazon Bedrock</h2>
    <p>Integrate your enterprise data into Amazon Bedrock using Pinecone to build highly performant GenAI applications.</p>
  </Card>

  <Card href="/integrations/amazon-sagemaker">
    <div>
      <SagemakerIcon />
    </div>

    <span>Frameworks</span>
    <h2>Amazon Sagemaker</h2>
    <p>Integrate machine learning models seamlessly with a fully-managed service that enables easy deployment and scalability.</p>
  </Card>

  <Card href="/integrations/anyscale">
    <div>
      <img />
    </div>

    <span>Models</span>
    <h2>Anyscale</h2>
    <p>Focus on building applications powered by LLMs without the need to worry about the underlying infrastructure.</p>
  </Card>

  <Card href="/integrations/apify">
    <div>
      <img />
    </div>

    <span>Data Sources</span>
    <h2>Apify</h2>
    <p>Integrate results from web scrapers or crawlers into a vector database to support RAG or semantic search over web content.</p>
  </Card>

  <Card href="/integrations/aryn">
    <div>
      <img />
    </div>

    <span>Data Sources</span>
    <h2>Aryn</h2>
    <p>Process complex, unstructured documents with a purpose-built ETL system for RAG and GenAI applications.</p>
  </Card>

  <Card href="/integrations/aws-marketplace">
    <div>
      <img />
    </div>

    <span>Infrastructure</span>
    <h2>AWS Marketplace</h2>
    <p>Access Pinecone through our AWS Marketplace listing.</p>
  </Card>

  <Card href="/integrations/box">
    <div>
      <img />
    </div>

    <span>Data Sources</span>
    <h2>Box</h2>
    <p>Connect a Box account to a Pinecone vector database.</p>
  </Card>

  <Card href="/integrations/claude-code">
    <span>IDEs & CLIs</span>
    <h2>Claude Code Plugin</h2>
    <p>Official Pinecone plugin for Claude Code with skills, MCP tools, and slash commands.</p>
  </Card>

  <Card href="/integrations/cloudera">
    <div>
      <img />
    </div>

    <span>Frameworks</span>
    <h2>Cloudera AI</h2>
    <p>Vector embedding, RAG, and semantic search at scale.</p>
  </Card>

  <Card href="/integrations/cohere">
    <div>
      <img />
    </div>

    <span>Models</span>
    <h2>Cohere</h2>
    <p>Leverage cutting-edge natural language processing tools for enhanced text understanding and generation in your applications.</p>
  </Card>

  <Card href="/integrations/confluent">
    <div>
      <img />
    </div>

    <span>Data Sources</span>
    <h2>Confluent</h2>
    <p>Connect and process all of your data in real time with a cloud-native and complete data streaming platform.</p>
  </Card>

  <Card href="/integrations/context-data">
    <div>
      <img />
    </div>

    <span>Frameworks</span>
    <h2>Context Data</h2>
    <p>Create end-to-end data flows that connect data sources to Pinecone.</p>
  </Card>

  <Card href="/integrations/databricks">
    <div>
      <img />
    </div>

    <span>Data Sources</span>
    <h2>Databricks</h2>
    <p>Combine the power of a unified analytics platform with Pinecone for scalable data processing and AI insights.</p>
  </Card>

  <Card href="/integrations/datadog">
    <div>
      <img />
    </div>

    <span>Observability</span>
    <h2>Datadog</h2>
    <p>Monitor and secure your applications by integrating with a cloud-scale monitoring service that provides real-time analytics.</p>
  </Card>

  <Card href="/integrations/datavolo">
    <div>
      <img />
    </div>

    <span>Data Sources</span>
    <h2>Datavolo</h2>
    <p>Source, transform, and enrich data in a continuous, composable and customizable manner.</p>
  </Card>

  <Card href="/integrations/estuary">
    <div>
      <img />
    </div>

    <span>Data Sources</span>
    <h2>Estuary</h2>
    <p>Source data from hundreds systems and push data to Pinecone, for an always up-to-date view.</p>
  </Card>

  <Card href="/integrations/flowise">
    <div>
      <img />
    </div>

    <span>Data Sources</span>
    <h2>FlowiseAI</h2>
    <p>Build customized LLM apps with an open source, low-code tool for developing orchestration flow & AI agents.</p>
  </Card>

  <Card href="/integrations/fleak">
    <div>
      <img />
    </div>

    <span>Data Sources</span>
    <h2>Fleak</h2>
    <p>Build, deploy, and manage complex workflows with a low-code platform for AI-assisted ML and LLM transformations.</p>
  </Card>

  <Card href="/integrations/gathr">
    <div>
      <img />
    </div>

    <span>Data Sources</span>
    <h2>Gathr</h2>
    <p>Build and operationalize data and AI-driven solutions at scale.</p>
  </Card>

  <Card href="/integrations/google-cloud-marketplace">
    <div>
      <img />
    </div>

    <span>Infrastructure</span>
    <h2>Google Cloud Marketplace</h2>
    <p>Access Pinecone through our Google Cloud Marketplace listing.</p>
  </Card>

  <Card href="/integrations/gemini-cli">
    <span>IDEs & CLIs</span>
    <h2>Gemini CLI Extension</h2>
    <p>Official Pinecone extension for Gemini CLI with skills and MCP tools.</p>
  </Card>

  <Card href="/integrations/genkit">
    <div>
      <img />
    </div>

    <span>Frameworks</span>
    <h2>Genkit</h2>
    <p>Build AI powered applications and agents.</p>
  </Card>

  <Card href="/integrations/github-copilot">
    <div>
      <img />
    </div>

    <span>IDEs & CLIs</span>
    <h2>GitHub Copilot</h2>
    <p>Get personalized recommendations that enable you to retrieve relevant data and collaborate effectively with Copilot.</p>
  </Card>

  <Card href="/integrations/haystack">
    <div>
      <img />
    </div>

    <span>Frameworks</span>
    <h2>Haystack</h2>
    <p>Implement an end-to-end search pipeline for efficient retrieval and question answering over large datasets.</p>
  </Card>

  <Card href="/integrations/honeyhive">
    <div>
      <img />
    </div>

    <span>Observability</span>
    <h2>HoneyHive</h2>
    <p>Clearly visualize your execution traces and spans.</p>
  </Card>

  <Card href="/integrations/hugging-face-inference-endpoints">
    <div>
      <img />
    </div>

    <span>Frameworks</span>
    <h2>Hugging Face</h2>
    <p>Deploy state-of-the-art machine learning models on scalable infrastructure, streamlining the path from prototype to production.</p>
  </Card>

  <Card href="/integrations/instill">
    <div>
      <img />
    </div>

    <span>Frameworks</span>
    <h2>Instill AI</h2>
    <p>Streamline AI development with a low-code full-stack infrastructure tool for data, model, and pipeline orchestration.</p>
  </Card>

  <Card href="/integrations/jina">
    <div>
      <img />
    </div>

    <span>Models</span>
    <h2>Jina</h2>
    <p>Leverage powerful AI models to generate high-quality text embeddings, fine-tuned to both domain- and language-specific use cases.</p>
  </Card>

  <Card href="/integrations/langchain">
    <div>
      <img />
    </div>

    <span>Frameworks</span>
    <h2>LangChain</h2>
    <p>Combine language models with chain-of-thought reasoning for advanced problem solving and decision support.</p>
  </Card>

  <Card href="/integrations/langtrace">
    <div>
      <img />
    </div>

    <span>Observability</span>
    <h2>Langtrace</h2>
    <p>Access rich and high cardinal tracing for Pinecone API calls, ingestible into your observability tool of choice.</p>
  </Card>

  <Card href="/integrations/llamaindex">
    <div>
      <img />
    </div>

    <span>Frameworks</span>
    <h2>Llama Index</h2>
    <p>Leverage Llama for indexing and retrieving information at scale, improving data access and analysis.</p>
  </Card>

  <Card href="/integrations/matillion">
    <div>
      <img />
    </div>

    <span>Data Sources</span>
    <h2>Matillion</h2>
    <p>Easily create and maintain data pipelines, build custom connectors for any source, and enjoy AI and high-code options to suit any need.</p>
  </Card>

  <Card href="/integrations/microsoft-marketplace">
    <div>
      <img />
    </div>

    <span>Infrastructure</span>
    <h2>Microsoft Marketplace</h2>
    <p>Access Pinecone through our Microsoft Marketplace listing.</p>
  </Card>

  <Card href="/integrations/n8n">
    <div>
      <img alt="n8n" />
    </div>

    <span>Frameworks</span>
    <h2>n8n</h2>
    <p>Build AI workflows with the Pinecone Assistant or Vector Store node—managed RAG or full control over your pipeline.</p>
  </Card>

  <Card href="/integrations/new-relic">
    <div>
      <img />
    </div>

    <span>Observability</span>
    <h2>New Relic</h2>
    <p>Implement monitoring and integrate your Pinecone application with New Relic for performance analysis and insights.</p>
  </Card>

  <Card href="/integrations/nexla">
    <div>
      <img />
    </div>

    <span>Data Sources</span>
    <h2>Nexla</h2>
    <p>Ingest data from 500+ connectors with Nexla's low-code/no-code AI integration platform.</p>
  </Card>

  <Card href="/integrations/nuclia">
    <div>
      <img />
    </div>

    <span>Frameworks</span>
    <h2>Nuclia</h2>
    <p>Nuclia RAG-as-a-Service automatically indexes files and documents from both internal and external sources.</p>
  </Card>

  <Card href="/integrations/octoai">
    <div>
      <img />
    </div>

    <span>Frameworks</span>
    <h2>OctoAI</h2>
    <p>Harness value from the latest AI innovations by delievering efficient, reliable, and customizable AI systems for your apps.</p>
  </Card>

  <Card href="/integrations/openai">
    <div>
      <OpenAIIcon />
    </div>

    <span>Models</span>
    <h2>OpenAI</h2>
    <p>Access powerful AI models like GPT for innovative applications and services, enhancing user experiences with AI capabilities.</p>
  </Card>

  <Card href="/integrations/pulumi">
    <div>
      <img />
    </div>

    <span>Infrastructure</span>
    <h2>Pulumi</h2>
    <p>Manage your Pinecone collections and indexes using any language of Pulumi Infrastructure as Code.</p>
  </Card>

  <Card href="/integrations/redpanda">
    <div>
      <img />
    </div>

    <span>Data Sources</span>
    <h2>Redpanda</h2>
    <p>Connect existing data sources to Pinecone with a Kafka-compatible streaming data platform built for data-intensive applications.</p>
  </Card>

  <Card href="/integrations/snowflake">
    <div>
      <img />
    </div>

    <span>Data Sources</span>
    <h2>Snowflake</h2>
    <p>Run Pinecone with Snowpark Container Services, designed to deploy, manage, and scale containerized applications within the Snowflake ecosystem.</p>
  </Card>

  <Card href="/integrations/streamnative">
    <div>
      <img />
    </div>

    <span>Data Sources</span>
    <h2>StreamNative</h2>
    <p>A scalable, resilient, and secure messaging and event streaming platform.</p>
  </Card>

  <Card href="/integrations/terraform">
    <div>
      <img />
    </div>

    <span>Infrastructure</span>
    <h2>Terraform</h2>
    <p>Manage your infrastructure using configuration files for a consistent workflow.</p>
  </Card>

  <Card href="/integrations/traceloop">
    <div>
      <img />
    </div>

    <span>Observability</span>
    <h2>Traceloop</h2>
    <p>Produce traces and metrics that can be viewed in any OpenTelemetry-based platform.</p>
  </Card>

  <Card href="/integrations/trulens">
    <div>
      <img />
    </div>

    <span>Observability</span>
    <h2>TruLens</h2>
    <p>Gain insights into your machine learning models' decisions, improving interpretability and trustworthiness.</p>
  </Card>

  <Card href="/integrations/twelve-labs">
    <div>
      <img />
    </div>

    <span>Models</span>
    <h2>Twelve Labs</h2>
    <p>Create high-quality multimodal embeddings that capture the rich context and interactions between different modalities in videos.</p>
  </Card>

  <Card href="/integrations/unstructured">
    <div>
      <img />
    </div>

    <span>Data Source</span>
    <h2>Unstructured</h2>
    <p>Load data into Pinecone with a single click.</p>
  </Card>

  <Card href="/integrations/vercel">
    <div>
      <img />
    </div>

    <span>Infrastructure</span>
    <h2>Vercel</h2>
    <p>Use Pinecone as the long-term memory for your Vercel AI projects, and easily scale to support billions of data points.</p>
  </Card>

  <Card href="/integrations/voltagent">
    <div>
      <img />
    </div>

    <span>Frameworks</span>
    <h2>VoltAgent</h2>
    <p>A TypeScript-based, AI-agent framework for building AI applications with retrieval-augmented generation (RAG) capabilities.</p>
  </Card>

  <Card href="/integrations/voyage">
    <div>
      <img />
    </div>

    <span>Models</span>
    <h2>Voyage AI</h2>
    <p>Cutting-edge embedding models and rerankers for semantic search and RAG.</p>
  </Card>

  <Card href="/integrations/zapier">
    <div>
      <img />
    </div>

    <span>Infrastructure</span>
    <h2>Zapier</h2>
    <p>Zapier connects Pinecone to thousands of apps to help you automate your work. No code required.</p>
  </Card>
</CardGroup>


# Model Gallery
Source: https://docs.pinecone.io/models/overview

Browse Pinecone's hosted embedding and reranking model gallery with details on dimensions, sequence length, pricing, and supported tasks.

<div>
  <span>
    <span>
      <svg>
        <path />
      </svg>
    </span>

    <span>
      <span>Inference</span>
    </span>
  </span>

  <div>
    <p>
      Build end-to-end faster with models hosted by Pinecone.
    </p>

    <a href="https://www.pinecone.io/request-a-model/">
      Request a model
    </a>
  </div>
</div>

<div>
  <div>
    <ModelCard description="State of the art text embedding model" />

    <ModelCard description="Top performing text embedding model from Microsoft research." />

    <ModelCard description="Cohere's latest reranker, with multilingual capabilities." />

    <ModelCard description="Cohere's previous-generation reranker. Deprecated; migrate to cohere-rerank-4-fast." />

    <ModelCard description="Sparse-vector encoder for custom lexical retrieval. For general keyword search, use full-text search." />

    <ModelCard description="High performance multi-lingual reranker model." />
  </div>

  <button aria-label="Previous slide">
    <svg>
      <path />
    </svg>
  </button>

  <button aria-label="Next slide">
    <svg>
      <path />
    </svg>
  </button>
</div>

<div>
  <iframe />
</div>


# Authentication
Source: https://docs.pinecone.io/reference/api/authentication

Pinecone API authentication guide covering API key generation, SDK client setup, and HTTP header configuration for authorized requests.

All requests to [Pinecone APIs](/reference/api/introduction) must contain a valid [API key](/guides/production/security-overview#api-keys) for the target project.

## Get an API key

[Create a new API key](https://app.pinecone.io/organizations/-/projects/-/keys) in the Pinecone console, or use the connect widget below to generate a key.

<div>
  <div>
    <div>
      <div />
    </div>
  </div>
</div>

Copy your generated key:

```
PINECONE_API_KEY="{{YOUR_API_KEY}}"

# This API key has ReadWrite access to all indexes in your project.
```

## Initialize a client

When using a [Pinecone SDK](/reference/pinecone-sdks), initialize a client object with your API key and then reuse the authenicated client in subsquent function calls. For example:

<CodeGroup>
  ```Python Python theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone
  from pinecone import ServerlessSpec

  pc = Pinecone(api_key='YOUR_API_KEY')

  # Creates an index using the API key stored in the client 'pc'.
  pc.create_index(
      name="docs-example",
      dimension=1536,
      metric="cosine",
      spec=ServerlessSpec(
          cloud='aws', 
          region='us-east-1'
      ) 
  ) 
  ```

  ```JavaScript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone';

  const pc = new Pinecone({
      apiKey: 'YOUR_API_KEY' 
  });

  // Creates an index using the API key stored in the client 'pc'.
  await pc.createIndex({
      name: 'docs-example',
      dimension: 1536,
      metric: 'cosine',
      spec: { 
          serverless: { 
              cloud: 'aws', 
              region: 'us-east-1' 
          }
      } 
  }) 
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Pinecone;
  import org.openapitools.db_control.client.model.IndexModel;
  import org.openapitools.db_control.client.model.DeletionProtection;

  public class CreateServerlessIndexExample {
      public static void main(String[] args) {
          Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build();

          // Creates an index using the API key stored in the client 'pc'.
          pc.createServerlessIndex("docs-example", "cosine", 1536, "aws", "us-east-1");
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "fmt"
      "log"

      "github.com/pinecone-io/go-pinecone/v3/pinecone"
  )

  func main() {
      ctx := context.Background()

      pc, err := pinecone.NewClient(pinecone.NewClientParams{
          ApiKey: "YOUR_API_KEY",
      })
      if err != nil {
          log.Fatalf("Failed to create Client: %v", err)
      }

  	indexName := "docs-example"
  	vectorType := "dense"
      dimension := int32(1536)
      metric := pinecone.Cosine
  	deletionProtection := pinecone.DeletionProtectionDisabled

      idx, err := pc.CreateServerlessIndex(ctx, &pinecone.CreateServerlessIndexRequest{
          Name:               indexName,
          VectorType:         &vectorType,
          Dimension:          &dimension,
          Metric:             &metric,
          Cloud:              pinecone.Aws,
          Region:             "us-east-1",
          DeletionProtection: &deletionProtection,
      })
      if err != nil {
          log.Fatalf("Failed to create serverless index: %v", err)
      } else {
          fmt.Printf("Successfully created serverless index: %v", idx.Name)
      }
  }
  ```

  ```shell curl theme={null}
  curl -s "https://api.pinecone.io/indexes" \
      -H "Api-Key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -H "X-Pinecone-Api-Version: 2025-10" \
      -d '{
          "name":  "docs-example",
          "dimension": 1536,
          "metric": "cosine",
          "spec": {
              "serverless": {
                 "cloud":"aws",
                 "region": "us-east-1"
              }
          }
      }'
  ```
</CodeGroup>

## Add headers to an HTTP request

All HTTP requests to Pinecone APIs must contain an `Api-Key` header that specifies a valid [API key](/guides/production/security-overview#api-keys) and must be encoded as JSON with the `Content-Type: application/json` header. For example:

```shell curl theme={null}
curl https://api.pinecone.io/indexes \
   -H "Content-Type: application/json" \
   -H "Api-Key: $PINECONE_API_KEY" \
  -H "X-Pinecone-Api-Version: 2025-10" \
   -d '{
         "name":  "docs-example",
         "dimension": 1536,
         "metric": "cosine",
         "spec": {
            "serverless": {
               "cloud":"aws",
               "region": "us-east-1"
            }
         }
      }'
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Initialization errors due to outdated SDKs">
    Older versions of Pinecone required you to initialize a client with an `init` method that takes both `api_key` and `environment` parameters, for example:

    <CodeGroup>
      ```python Python theme={null}
      # Legacy initialization
      import pinecone

      pc = pinecone.init(
          api_key="PINECONE_API_KEY",
          environment="PINECONE_ENVIRONMENT"
      )
      ```

      ```javascript JavaScript theme={null}
      // Legacy initialization
      import { Pinecone } from '@pinecone-database/pinecone';

      const pineconeClient = new PineconeClient();
      await pineconeClient.init({
          apiKey: 'PINECONE_API_KEY',
          environment: 'PINECONE_ENVIRONMENT',
      });
      ```
    </CodeGroup>

    In more recent versions of Pinecone, this has changed. Initialization no longer requires an `init` step, and cloud environment is defined for each index rather than an entire project. Client initialization now only requires an `api_key` parameter, for example:

    <CodeGroup>
      ```python Python theme={null}
      # New initialization
      from pinecone import Pinecone

      pc = Pinecone(api_key="YOUR_API_KEY")
      ```

      ```javascript JavaScript theme={null}
      // New initialization
      import { Pinecone } from '@pinecone-database/pinecone';

      const pc = new Pinecone({
          apiKey: 'YOUR_API_KEY' 
      });
      ```
    </CodeGroup>

    If you are receiving errors about initialization, upgrade your [Pinecone SDK](/reference/pinecone-sdks) to the latest version, for example:

    <CodeGroup>
      ```shell Python theme={null}
      # Upgrade Pinecone SDK
      pip install pinecone --upgrade
      ```

      ```shell JavaScript theme={null}
      # Upgrade Pinecone SDK
      npm install @pinecone-database/pinecone@latest
      ```
    </CodeGroup>

    Also, note that some third-party tutorials and examples still reference the older initialization method. In such cases, follow the example above and the examples throughout the Pinecone documentation instead.
  </Accordion>
</AccordionGroup>


# Pinecone Database limits
Source: https://docs.pinecone.io/reference/api/database-limits

Reference for Pinecone Database limits, covering upsert, query, fetch, delete, import, namespace, and rate limits for serverless indexes.

This page describes different types of limits for Pinecone Database.

<Note>
  **Looking for a specific limit?**

  * To compare monthly included usage by plan, start with [read units](#read-units-per-month-per-org), [write units](#write-units-per-month-per-org), and [model usage limits](#monthly-usage-limits).
  * If you received a `429` error, check [rate limits](#rate-limits), especially request-per-second limits for query, upsert, update, delete, fetch, and list.
  * For projects, users, indexes, namespaces, storage, backups, and collections, see [object limits](#object-limits).
  * For batch sizes, metadata filters, and identifier lengths, see [operation limits](#operation-limits) and [identifier limits](#identifier-limits).
</Note>

## Rate limits

Rate limits help protect your applications from misuse and maintain the health of our shared serverless infrastructure. These limits are designed to support typical production workloads while ensuring reliable performance for all users.

**Most rate limits can be adjusted upon request.** If you need higher limits to scale your application, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) with details about your use case. Pinecone is committed to supporting your growth and can often accommodate higher throughput requirements.

Rate limits vary based on [pricing plan](https://www.pinecone.io/pricing/) and apply to [serverless indexes](/guides/index-data/indexing-overview) only.

<Note>
  Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide.
</Note>

### Data plane operations: request-per-second limits

Pinecone enforces rate limits on the number of API requests per second at the namespace level for data plane operations (query, upsert, delete, and update). These limits provide protection against excessive request rates.

#### Affected operations

The following operations are subject to request-per-second rate limiting:

| Operation | Scope         | Limit |
| --------- | ------------- | ----- |
| Query     | Per namespace | 100   |
| Upsert    | Per namespace | 100   |
| Delete    | Per namespace | 100   |
| Update    | Per namespace | 100   |

#### Error response

When you exceed the request-per-second limit, you'll receive an HTTP `429 - TOO_MANY_REQUESTS` response. The error message indicates which operation exceeded the limit and includes the namespace name and limit value. See the individual limit sections below for specific error message formats.

#### How request-per-second limits work with limits on read and write units

Request-per-second limits are enforced in addition to existing read unit and write unit limits. Requests must not exceed any applicable limits:

* Index-level limits - read and write unit limits, per index
* Namespace-level limits - read and write unit limits, per namespace
* Request-per-second limits - requests per second, per namespace

If any limit is exceeded, the request fails with a 429 error.

#### Recommendations

If you're hitting request-per-second limits:

1. Implement retry logic. Use exponential backoff to handle rate limit errors gracefully. See [Error Handling Guide](/guides/production/error-handling#implement-retry-logic).
2. Pace your requests. Add client-side rate limiting to stay under limits.
3. Consider [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes), which don't have request-per-second limits and provide dedicated capacity for high-throughput workloads.
4. If you need higher limits, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) with details about your use case.

### All rate limits

#### Monthly usage limits

| Metric                                                                        | Starter plan   | Builder plan   | Standard plan  | Enterprise plan |
| :---------------------------------------------------------------------------- | :------------- | :------------- | :------------- | :-------------- |
| [Read units per month per org](#read-units-per-month-per-org)                 | 1,000,000      | 2,000,000      | Unlimited      | Unlimited       |
| [Write units per month per org](#write-units-per-month-per-org)               | 2,000,000      | 5,000,000      | Unlimited      | Unlimited       |
| [Embedding tokens per month per model](#embedding-tokens-per-month-per-model) | 5,000,000      | 10,000,000     | Unlimited      | Unlimited       |
| [Rerank requests per month per model](#rerank-requests-per-month-per-model)   | Model-specific | Model-specific | Model-specific | Model-specific  |

#### Data operation throughput limits

| Metric                                                                                                        | Starter plan | Builder plan | Standard plan | Enterprise plan |
| :------------------------------------------------------------------------------------------------------------ | :----------- | :----------- | :------------ | :-------------- |
| [Upsert size per second per namespace](#upsert-size-per-second-per-namespace)                                 | 50 MB        | 50 MB        | 50 MB         | 50 MB           |
| [Query read units per second per index](#query-read-units-per-second-per-index)                               | 2,000        | 2,000        | 2,000         | 2,000           |
| [Query requests per second per namespace](#query-requests-per-second-per-namespace)                           | 100          | 100          | 100           | 100             |
| [Update records per second per namespace](#update-records-per-second-per-namespace)                           | 100          | 100          | 100           | 100             |
| [Update requests per second per namespace](#update-requests-per-second-per-namespace)                         | 100          | 100          | 100           | 100             |
| [Update by metadata requests per second per namespace](#update-by-metadata-requests-per-second-per-namespace) | 5            | 5            | 5             | 5               |
| [Update by metadata requests per second per index](#update-by-metadata-requests-per-second-per-index)         | 500          | 500          | 500           | 500             |
| [Upsert requests per second per namespace](#upsert-requests-per-second-per-namespace)                         | 100          | 100          | 100           | 100             |
| [Fetch requests per second per index](#fetch-requests-per-second-per-index)                                   | 100          | 100          | 100           | 100             |
| [List requests per second per index](#list-requests-per-second-per-index)                                     | 200          | 200          | 200           | 200             |
| [Describe index stats requests per second per index](#describe-index-stats-requests-per-second-per-index)     | 100          | 100          | 100           | 100             |
| [Delete requests per second per namespace](#delete-requests-per-second-per-namespace)                         | 100          | 100          | 100           | 100             |
| [Delete records per second per namespace](#delete-records-per-second-per-namespace)                           | 5,000        | 5,000        | 5,000         | 5,000           |
| [Delete records per second per index](#delete-records-per-second-per-index)                                   | 5,000        | 5,000        | 5,000         | 5,000           |
| [Delete by metadata requests per second per namespace](#delete-by-metadata-requests-per-second-per-namespace) | 5            | 5            | 5             | 5               |
| [Delete by metadata requests per second per index](#delete-by-metadata-requests-per-second-per-index)         | 500          | 500          | 500           | 500             |

#### Model throughput limits

| Metric                                                                          | Starter plan   | Builder plan   | Standard plan  | Enterprise plan |
| :------------------------------------------------------------------------------ | :------------- | :------------- | :------------- | :-------------- |
| [Embedding tokens per minute per model](#embedding-tokens-per-minute-per-model) | Model-specific | Model-specific | Model-specific | Model-specific  |
| [Rerank requests per minute per model](#rerank-requests-per-minute-per-model)   | Model-specific | Model-specific | Model-specific | Model-specific  |

### Read units per month per org

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 1,000,000    | 2,000,000    | Unlimited     | Unlimited       |

[Read units](/guides/manage-cost/understanding-cost#read-units) measure the compute, I/O, and network resources used by [fetch](/guides/manage-data/fetch-data), [query](/guides/search/search-overview), and [list](/guides/manage-data/list-record-ids) requests to serverless indexes. When you reach the monthly read unit limit for an organization, fetch, query, and list requests to serverless indexes in the organization will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached your read unit limit for the current month limit. 
  To continue reading data, upgrade your plan. 
  ```
</Accordion>

To continue reading from serverless indexes in the organization, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan).

To check how close you are to the monthly read unit limit for your organization, do the following:

1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects).
2. Select the project.
3. Select any index in the project.
4. Look under **Usage**.

<Note>
  Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide.
</Note>

### Write units per month per org

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 2,000,000    | 5,000,000    | Unlimited     | Unlimited       |

[Write units](/guides/manage-cost/understanding-cost#write-units) measure the storage and compute resources used by [upsert](/guides/index-data/upsert-data), [update](/guides/manage-data/update-data), and [delete](/guides/manage-data/delete-data) requests to serverless indexes. When you reach the monthly write unit limit for an organization, upsert, update, and delete requests to serverless indexes in the organization will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached your write unit limit for the current month. 
  To continue writing data, upgrade your plan.
  ```
</Accordion>

To continue writing data to serverless indexes in the organization, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan).

To check how close you are to the monthly write unit limit for your organization, do the following:

1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects).
2. Select the project.
3. Select any index in the project.
4. Look under **Usage**.

### Upsert size per second per namespace

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 50 MB        | 50 MB        | 50 MB         | 50 MB           |

When you reach the per second [upsert](/guides/index-data/upsert-data) size for a namespace in an index, additional upserts will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max upsert size limit per second for index <index name>. 
  Pace your upserts or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Query read units per second per index

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 2,000        | 2,000        | 2,000         | 2,000           |

Pinecone measures [query](/guides/search/search-overview) usage in [read units](/guides/manage-cost/understanding-cost#read-units). When you reach the per second limit for queries across all namespaces in an index, additional queries will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max query read units per second for index <index name>. 
  Pace your queries or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

To check how many read units a query consumes, [check the query response](/guides/manage-cost/monitor-usage-and-costs#read-units).

<Note>
  Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide.
</Note>

### Query requests per second per namespace

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 100          | 100          | 100           | 100             |

When you reach the per second [query](/guides/search/search-overview) limit for a namespace in an index, additional queries will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the query QPS limit for namespace {namespace_name} ({limit} QPS). Pace your queries,
  consider Dedicated Read Nodes for your index, or contact Pinecone Support
  (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

<Note>
  Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide.
</Note>

### Update records per second per namespace

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 100          | 100          | 100           | 100             |

When you reach the per second [update](/guides/manage-data/update-data) limit for a namespace in an index, additional updates will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max update records per second for namespace <namespace name>. 
  Pace your update requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Update requests per second per namespace

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 100          | 100          | 100           | 100             |

When you reach the per second [update](/guides/manage-data/update-data) request limit for a namespace in an index, additional update requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the update QPS limit for namespace {namespace_name} ({limit} QPS). Pace your update requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

<Tip>
  If you need to update most of the records in a large namespace, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) for help creating an export to enable a faster and more cost-effective approach.
</Tip>

### Update by metadata requests per second per namespace

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 5            | 5            | 5             | 5               |

When you reach the per second [update by metadata](/guides/manage-data/update-data#update-metadata-across-multiple-records) request limit for a namespace in an index, additional update by metadata requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max update by metadata requests per second for namespace <namespace name>. Pace your update by metadata requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Update by metadata requests per second per index

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 500          | 500          | 500           | 500             |

When you reach the per second [update by metadata](/guides/manage-data/update-data#update-metadata-across-multiple-records) request limit across all namespaces in an index, additional update by metadata requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max update by metadata requests per second for index <index name>. Pace your update by metadata requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Upsert requests per second per namespace

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 100          | 100          | 100           | 100             |

When you reach the per second [upsert](/guides/index-data/upsert-data) request limit for a namespace in an index, additional upsert requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the upsert QPS limit for namespace {namespace_name} ({limit} QPS). Pace your upsert requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Fetch requests per second per index

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 100          | 100          | 100           | 100             |

When you reach the per second [fetch](/guides/manage-data/fetch-data) limit across all namespaces in an index, additional fetch requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max fetch requests per second for index <index name>.
  Pace your fetch requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

<Note>
  Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide.
</Note>

### List requests per second per index

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 200          | 200          | 200           | 200             |

When you reach the per second [list](/guides/manage-data/list-record-ids) limit across all namespaces in an index, additional list requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max list requests per second for index <index name>.
  Pace your list requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

<Note>
  Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide.
</Note>

### Describe index stats requests per second per index

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 100          | 100          | 100           | 100             |

When you reach the per second [describe index stats](/reference/api/2024-10/data-plane/describeindexstats) limit across all namespaces in an index, additional describe index stats requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max describe_index_stats requests per second for index <index>. 
  Pace your describe_index_stats requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Delete requests per second per namespace

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 100          | 100          | 100           | 100             |

When you reach the per second [delete](/guides/manage-data/delete-data) request limit for a namespace in an index, additional delete requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the delete QPS limit for namespace {namespace_name} ({limit} QPS). Pace your delete requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Delete records per second per namespace

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 5000         | 5000         | 5000          | 5000            |

When you reach the per second [delete](/guides/manage-data/delete-data) limit for a namespace in an index, additional deletes will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max delete records per second for namespace <namespace name>. 
  Pace your delete requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Delete records per second per index

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 5000         | 5000         | 5000          | 5000            |

When you reach the per second [delete](/guides/manage-data/delete-data) limit across all namespaces in an index, additional deletes will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max delete records per second for index <index name>. 
  Pace your delete requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Delete by metadata requests per second per namespace

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 5            | 5            | 5             | 5               |

When you reach the per second [delete by metadata](/guides/manage-data/delete-data#delete-records-by-metadata) request limit for a namespace in an index, additional delete by metadata requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max delete by metadata requests per second for namespace <namespace name>. Pace your delete by metadata requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Delete by metadata requests per second per index

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 500          | 500          | 500           | 500             |

When you reach the per second [delete by metadata](/guides/manage-data/delete-data#delete-records-by-metadata) request limit across all namespaces in an index, additional delete by metadata requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max delete by metadata requests per second for index <index name>. Pace your delete by metadata requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit.
  ```
</Accordion>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Embedding tokens per minute per model

| Embedding model              | Input type | Starter plan | Builder plan | Standard plan | Enterprise plan |
| :--------------------------- | :--------- | :----------- | :----------- | :------------ | :-------------- |
| `llama-text-embed-v2`        | Passage    | 250,000      | 250,000      | 1,000,000     | 1,000,000       |
|                              | Query      | 50,000       | 50,000       | 250,000       | 250,000         |
| `multilingual-e5-large`      | Passage    | 250,000      | 250,000      | 1,000,000     | 1,000,000       |
|                              | Query      | 50,000       | 50,000       | 250,000       | 250,000         |
| `pinecone-sparse-english-v0` | Passage    | 250,000      | 250,000      | 3,000,000     | 3,000,000       |
|                              | Query      | 250,000      | 250,000      | 3,000,000     | 3,000,000       |

When you reach the per minute token limit for an [embedding model](/guides/index-data/create-an-index#embedding-models) hosted by Pinecone, additional embeddings will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max embedding tokens per minute (<limit>) model '<model name>'' and input type '<passage|query>' for the current project. 
  To increase this limit, upgrade your plan.
  ```
</Accordion>

To increase this limit, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). Otherwise, you can handle this limit by [implementing retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic).

### Embedding tokens per month per model

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 5,000,000    | 10,000,000   | Unlimited     | Unlimited       |

When you reach the monthly token limit for an [embedding model](/guides/index-data/create-an-index#embedding-models) hosted by Pinecone, additional embeddings will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the embedding token limit (<limit>) for model <model name> for the current month. 
  To continue using this model, upgrade your plan.
  ```
</Accordion>

To increase this limit, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan) or [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Rerank requests per minute per model

| Reranking model        | Starter plan  | Builder plan  | Standard plan | Enterprise plan |
| :--------------------- | :------------ | :------------ | :------------ | :-------------- |
| `cohere-rerank-4-fast` | Not available | Not available | 300           | 300             |
| `cohere-rerank-3.5`    | Not available | Not available | 300           | 300             |
| `bge-reranker-v2-m3`   | 60            | 60            | 60            | 60              |
| `pinecone-rerank-v0`   | 60            | Not available | 60            | 60              |

When you reach the per minute request limit for a [reranking model](/guides/search/rerank-results#reranking-models) hosted by Pinecone, additional reranking requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max rerank requests per minute (<limit>) for model '<model name>' for the current project. 
  To increase this limit, upgrade your plan.
  ```
</Accordion>

To increase this limit, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan).

### Rerank requests per month per model

| Reranking model        | Starter plan  | Builder plan  | Standard plan | Enterprise plan |
| :--------------------- | :------------ | :------------ | :------------ | :-------------- |
| `cohere-rerank-4-fast` | Not available | Not available | Unlimited     | Unlimited       |
| `cohere-rerank-3.5`    | Not available | Not available | Unlimited     | Unlimited       |
| `bge-reranker-v2-m3`   | 500           | 1,000         | Unlimited     | Unlimited       |
| `pinecone-rerank-v0`   | 500           | Not available | Unlimited     | Unlimited       |

When you reach the monthly request limit for a [reranking model](/guides/search/rerank-results#reranking-models) hosted by Pinecone, additional reranking requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the rerank request limit (<limit>) for model <model name> for the current month. 
  To continue using this model, upgrade your plan.
  ```
</Accordion>

To increase this limit, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan) or [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Inference requests per second or minute, per project

| Metric                        | Starter plan | Builder plan | Standard plan | Enterprise plan |
| :---------------------------- | :----------- | :----------- | :------------ | :-------------- |
| Inference requests per second | 100          | 100          | 100           | 100             |
| Inference requests per minute | 2000         | 2000         | 2000          | 2000            |

When you reach the per second or per minute request limit, inference requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max inference requests per second (<limit>) for the current project.
  ```
</Accordion>

<Note>
  This error indicates per second or per minute, as applicable.
</Note>

To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic).

## Object limits

Object limits are restrictions on the number or size of objects in Pinecone. Object limits vary based on [pricing plan](https://www.pinecone.io/pricing/).

| Metric                                                                         | Starter plan | Builder plan | Standard plan | Enterprise plan |
| :----------------------------------------------------------------------------- | :----------- | :----------- | :------------ | :-------------- |
| [Projects per organization](#projects-per-organization)                        | 1            | 5            | 20            | 100             |
| [Users per organization](#users-per-organization)                              | 2            | 5            | Unlimited     | Unlimited       |
| [Serverless indexes per project](#serverless-indexes-per-project) <sup>1</sup> | 5            | 10           | 20            | 200             |
| [Serverless index storage per org](#serverless-index-storage-per-org)          | 2 GB         | 10 GB        | N/A           | N/A             |
| [Namespaces per serverless index](#namespaces-per-serverless-index)            | 100          | 1,000        | 100,000       | 100,000         |
| [Serverless backups per project](#serverless-backups-per-project)              | N/A          | N/A          | 500           | 1000            |
| [Collections per project](#collections-per-project)                            | 100          | N/A          | N/A           | N/A             |

<sup>1 On the Starter plan, all serverless indexes must be in the `us-east-1` region of AWS. Builder, Standard, and Enterprise plans can create indexes in any [supported region](/guides/index-data/create-an-index#cloud-regions).</sup><br />

### Projects per organization

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 1            | 5            | 20            | 100             |

When you reach this quota for an organization, trying to [create projects](/guides/projects/create-a-project) will fail and return a `403 - QUOTA_EXCEEDED` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max projects allowed in organization <org name>. 
  To add more projects, upgrade your plan.
  ```
</Accordion>

To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan) or [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

### Users per organization

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 2            | 5            | Unlimited     | Unlimited       |

When you reach this quota for an organization, trying to add users to the organization will fail. To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan).

### Serverless indexes per project

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 5            | 10           | 20            | 200             |

When you reach this quota for a project, trying to [create serverless indexes](/guides/index-data/create-an-index#create-a-serverless-index) in the project will fail and return a `403 - QUOTA_EXCEEDED` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max serverless indexes allowed in project <project>. 
  Use namespaces to partition your data into logical groups, or upgrade your plan to add more serverless indexes.
  ```
</Accordion>

To stay under this quota, consider using [namespaces](/guides/index-data/create-an-index#namespaces) instead of creating multiple indexes. Namespaces let you partition your data into logical groups within a single index. This approach not only helps you stay within index limits, but can also improve query performance and lower costs by limiting searches to relevant data subsets.

To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan).

### Serverless index storage per org

<Note>This limit applies to organizations on the Starter and Builder plans only.</Note>

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 2 GB         | 10 GB        | N/A           | N/A             |

When you've reached this quota for an organization, updates and upserts into serverless indexes will fail and return a `403 - QUOTA_EXCEEDED` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max storage allowed for organization <org name>. 
  To update or upsert new data, delete records or upgrade your plan.
  ```
</Accordion>

To continue writing data into your serverless indexes, [delete records](/guides/manage-data/delete-data) to bring your organization under the limit or [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan).

### Namespaces per serverless index

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 100          | 1,000        | 100,000       | 100,000         |

When you reach this quota for a serverless index, trying to [upsert records into a new namespace](/guides/index-data/upsert-data) in the index will fail and return a `403 - QUOTA_EXCEEDED` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max namespaces allowed in serverless index <index name>. 
  To add more namespaces, upgrade your plan.
  ```
</Accordion>

To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan).

<Note>
  [Namespaces per serverless index](/reference/api/database-limits#namespaces-per-serverless-index) vary by plan. On the Standard and Enterprise plans, Pinecone can accommodate million-scale namespaces and beyond for specific use cases. If your application requires more than 100,000 namespaces, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).
</Note>

### Serverless backups per project

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| N/A          | N/A          | 500           | 1000            |

Backups are not available on the Starter or Builder plans. On the Standard and Enterprise plans, when you reach this quota for a project, trying to [create serverless backups](/guides/manage-data/back-up-an-index) in the project will fail and return a `403 - QUOTA_EXCEEDED` status with the following error:

<Accordion title="Error response">
  ```
  Backup failed to create. Quota for number of backups per index exceeded.
  ```
</Accordion>

### Collections per project

| Starter plan | Builder plan | Standard plan | Enterprise plan |
| ------------ | ------------ | ------------- | --------------- |
| 100          | N/A          | N/A           | N/A             |

When you reach this quota for a project, trying to [create collections](/guides/manage-data/back-up-an-index) in the project will fail and return a `403 - QUOTA_EXCEEDED` status with the following error:

<Accordion title="Error response">
  ```
  Request failed. You've reached the max collections allowed in project <project name>. 
  To add more collections, upgrade your plan.
  ```
</Accordion>

To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan).

## Operation limits

Operation limits are restrictions on the size, number, or other characteristics of operations in Pinecone. Operation limits are fixed and do not vary based on pricing plan.

### Upsert limits

| Metric                                                             | Limit                                                         |
| :----------------------------------------------------------------- | :------------------------------------------------------------ |
| Max [batch size](/guides/index-data/upsert-data#upsert-in-batches) | 2 MB or 1000 records with vectors <br /> 96 records with text |
| Max documents per upsert request                                   | 1000                                                          |
| Max document upsert request size                                   | 2 MB                                                          |
| Max document size                                                  | 2 MB                                                          |
| Max `full_text_search` string fields per schema                    | 100                                                           |
| Max size per `full_text_search` string field                       | 100 KB                                                        |
| Max tokens per `full_text_search` string field                     | 10,000                                                        |
| Max bytes per token                                                | 256 bytes                                                     |
| Max filterable metadata size per document                          | 40 KB                                                         |
| Max length for a record ID                                         | 512 characters                                                |
| Max dimensionality for dense vectors                               | 20,000                                                        |
| Max non-zero values for sparse vectors                             | 2048                                                          |
| Max dimensionality for sparse vectors                              | 4.2 billion                                                   |

The 40 KB filterable metadata limit does not apply to `full_text_search` text fields.

### Import limits

<Note>
  If your import exceeds these limits, you'll get an error specifying the limit exceeded. See [Troubleshooting](/guides/index-data/import-data#troubleshooting) for details.
</Note>

| Metric                                        | Limit     |
| :-------------------------------------------- | :-------- |
| Max namespaces per import                     | 10,000    |
| Max total input data size (on-demand indexes) | 1 TB      |
| Max total input data size (DRN indexes)       | Unlimited |
| Max files per import                          | 100,000   |
| Max size per file                             | 10 GB     |

The total input data size limit does not apply to indexes with [dedicated read nodes](/guides/index-data/dedicated-read-nodes).

Bulk import supports indexes without a schema definition (Parquet files) and indexes with document schemas ([JSONL files](/guides/search/full-text-search#bulk-import)). Semantic-text (auto-embedded) fields are not yet supported in document schemas.

### Query limits

| Metric            | Limit  |
| :---------------- | :----- |
| Max `top_k` value | 10,000 |
| Max result size   | 4MB    |

The query result size is affected by the dimension of the dense vectors and whether or not dense vector values and metadata are included in the result.

<Tip>
  If a query fails due to exceeding the 4MB result size limit, choose a lower `top_k` value, or use `include_metadata=False` or `include_values=False` to exclude metadata or values from the result. For better performance, especially with higher `top_k` values, avoid including vector values unless you need them.
</Tip>

### Fetch limits

**Fetch by ID limits:**

| Metric                           | Limit |
| :------------------------------- | :---- |
| Max record IDs per fetch request | 1,000 |

**Fetch by metadata limits:**

| Metric                   | Limit                               |
| :----------------------- | :---------------------------------- |
| Max records per response | 10,000                              |
| Max response size        | 4 MB                                |
| Max request rate         | 5 requests per second per namespace |

To retrieve more than 10,000 matching records, paginate through results using the `paginationToken` parameter. See [Fetch records by metadata](/guides/manage-data/fetch-data#fetch-records-by-metadata).

### Delete limits

| Metric                            | Limit |
| :-------------------------------- | :---- |
| Max record IDs per delete request | 1,000 |

### Metadata filter limits

The following limits apply to [metadata filter expressions](/guides/search/filter-by-metadata#metadata-filter-expressions) used in query, delete, update, and fetch operations.

| Limit                                       | Value  | Description                                                                                                                                                                                                      |
| :------------------------------------------ | :----- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Maximum values per `$in` or `$nin` operator | 10,000 | Each `$in` or `$nin` operator accepts up to 10,000 values in its array. This limit applies per operator—if you have multiple `$in` operators in a single filter, each is independently limited to 10,000 values. |

When you exceed this limit, the request will fail and return a `400 - BAD_REQUEST` error.

#### Rationale

Large `$in` operators can impact query performance and cost. Filters with thousands of values increase request payload size and end-to-end latency. Additionally, using large filters typically indicates a shared namespace architecture, which increases query costs—queries scan the entire namespace regardless of filters.

#### Alternative approaches

If you need to filter by more than 10,000 values, consider these alternatives:

* **Use namespaces for tenant isolation**: Instead of filtering by tenant IDs within a single namespace, create separate namespaces for each tenant or tenant group. This can also reduce query costs. See [Design for multi-tenancy](/guides/index-data/data-modeling#design-for-multi-tenancy).
* **Use broader access control groups**: Instead of filtering by individual user IDs, filter by organization, project, or role. This reduces the number of values in your `$in` filter. See [Design for multi-tenancy](/guides/index-data/data-modeling#use-access-control-groups-instead-of-individual-ids).
* **Post-filter client-side**: Retrieve a larger top K without filtering (for example, top 1000), then filter results client-side.
* **Run multiple queries**: Split your filter into multiple queries with smaller `$in` operators and combine the results client-side.

<Tip>
  To avoid hitting this limit in production, validate the size of your `$in` and `$nin` arrays in your application code before making the request to Pinecone.
</Tip>

## Identifier limits

An identifier is a string of characters used to identify "named" [objects in Pinecone](/guides/get-started/concepts). The following Pinecone objects use strings as identifiers:

| Object                                                    | Field       | Max # characters | Allowed characters                                                                                                                        |
| --------------------------------------------------------- | ----------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| [Organization](/guides/get-started/concepts#organization) | `name`      | 512              | <ul><li>UTF-8 except `\0`</li><li>Cannot be empty</li></ul>                                                                               |
| [Project](/guides/get-started/concepts#project)           | `name`      | 512              | <ul><li>UTF-8 except `\0`</li><li>Cannot be empty</li></ul>                                                                               |
| [Index](/guides/get-started/concepts#index)               | `name`      | 45               | <ul><li>`a-z`, `0-9`, and `-`</li><li>Must be lowercase</li><li>Cannot start or end with `-`</li><li>Cannot be empty</li></ul>            |
| [Namespace](/guides/get-started/concepts#namespace)       | `namespace` | 512              | <ul><li>ASCII except `\0`</li><li>For the default namespace, use `""` (or `"__default__"`, in API versions `2025-04` and later)</li></ul> |
| [Record](/guides/get-started/concepts#record)             | `id`        | 512              | <ul><li>ASCII except `\0`</li><li>Cannot be empty</li></ul>                                                                               |


# Errors
Source: https://docs.pinecone.io/reference/api/errors

Pinecone REST API: Pinecone uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the range.

Pinecone uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the `2xx` range indicate success, codes in the `4xx` range indicate an error that failed given the information provided, and codes in the `5xx` range indicate an error with Pinecone's servers.

For guidance on handling errors in production, see [Error handling](/guides/production/error-handling).

## 200 - OK

The request succeeded.

## 201 - CREATED

The request succeeded and a new resource was created.

## 202 - NO CONTENT

The request succeeded, but there is no content to return.

## 400 - INVALID ARGUMENT

The request failed due to an invalid argument.

## 401 - UNAUTHENTICATED

The request failed due to a missing or invalid [API key](/guides/projects/understanding-projects#api-keys).

## 402 - PAYMENT REQUIRED

The request failed due to delinquent payment or account deactivation for non-payment. See [Account deactivation for non-payment](/guides/organizations/manage-billing/non-payment-account-deactivation).

## 403 - FORBIDDEN

The request failed due to an exceeded [quota](/reference/api/database-limits#object-limits) or [index deletion protection](/guides/manage-data/manage-indexes#configure-deletion-protection).

## 404 - NOT FOUND

The request failed because the resource was not found.

## 409 - ALREADY EXISTS

The request failed because the resource already exists.

## 412 - FAILED PRECONDITIONS

The request failed due to preconditions not being met. |

## 422 - UNPROCESSABLE ENTITY

The request failed because the server was unable to process the contained instructions.

## 429 - TOO MANY REQUESTS

The request was [rate-limited](/reference/api/database-limits#rate-limits). [Implement retry logic with exponential backoff](/guides/production/error-handling#handle-rate-limits-429) to handle this error.

## 500 - UNKNOWN

An internal server error occurred. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) to handle transient errors.

## 502 - BAD GATEWAY

The API gateway received an invalid response from a backend service. This is typically a temporary error. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) to handle transient errors.

## 503 - UNAVAILABLE

The server is currently unavailable. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) to handle transient errors.

## 504 - GATEWAY TIMEOUT

The API gateway did not receive a timely response from the backend server. This can occur due to slow requests or backend processing delays. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) to handle transient errors.


# API reference
Source: https://docs.pinecone.io/reference/api/introduction

Pinecone API reference overview for Database, Inference, and Admin endpoints with supported SDKs including Python, Node.js, Java, and Go.

Pinecone's APIs let you interact programmatically with your Pinecone account.

<Note>
  [SDK versions](/reference/pinecone-sdks#sdk-versions) are pinned to specific API versions.
</Note>

## Database

Use the Database API to store and query records in [Pinecone Database](/guides/get-started/quickstart).

The following Pinecone SDKs support the Database API:

<CardGroup>
  <Card title="CLI" icon="terminal" href="/reference/cli/overview" />

  <Card title="Python SDK" icon="python" href="/reference/sdks/python/overview" />

  <Card title="Node.js SDK" icon="node-js" href="/reference/sdks/node/overview" />

  <Card title="Java SDK" icon="java" href="/reference/sdks/java/overview" />

  <Card title="Go SDK" icon="golang" href="/reference/sdks/go/overview" />
</CardGroup>

## Inference

Use the Inference API to generate vector embeddings and rerank results using [embedding models](/guides/index-data/create-an-index#embedding-models) and [reranking models](/guides/search/rerank-results#reranking-models) hosted on Pinecone's infrastructure.

There are two ways to use the Inference API:

* As a standalone service, through the [Rerank documents](/reference/api/latest/inference/rerank) and [Generate vectors](/reference/api/latest/inference/generate-embeddings) endpoints.
* As an integrated part of database operations, through the [Create an index with integrated embedding](/reference/api/latest/control-plane/create_for_model), [Upsert text](/reference/api/latest/data-plane/upsert_records), and [Search with text](/reference/api/latest/data-plane/search_records) endpoints.

The following Pinecone SDKs support using the Inference API:

<CardGroup>
  <Card title="Python SDK" icon="python" href="/reference/sdks/python/overview" />

  <Card title="Node.js SDK" icon="node-js" href="/reference/sdks/node/overview" />

  <Card title="Java SDK" icon="java" href="/reference/sdks/java/overview" />

  <Card title="Go SDK" icon="golang" href="/reference/sdks/go/overview" />
</CardGroup>


# Known limitations
Source: https://docs.pinecone.io/reference/api/known-limitations

Known limitations and feature restrictions for Pinecone indexes, including upsert consistency, metadata rules, and serverless caveats.

This page describes known limitations and feature restrictions in Pinecone.

## General

* [Upserts](/guides/index-data/upsert-data)
  * Pinecone is eventually consistent, so there can be a slight delay before upserted records are available to query.

    After upserting records, use the [`describe_index_stats`](/reference/api/2024-10/data-plane/describeindexstats) operation to check if the current vector count matches the number of records you expect, although this method may not work for pod-based indexes with multiple replicas.
  * Only indexes using the [dotproduct distance metric](/guides/index-data/indexing-overview#dotproduct) support querying sparse-dense vectors.

    Upserting, updating, and fetching sparse-dense vectors in indexes with a different distance metric will succeed, but querying will return an error.
  * Indexes created before February 22, 2023 do not support sparse vectors.
* [Metadata](/guides/index-data/upsert-data#upsert-with-metadata-filters)
  * Null metadata values aren't supported. Instead of setting a key to `null`, remove the key from the metadata payload.
  * Nested JSON objects are not supported.

## Serverless indexes

Serverless indexes do not support the following features:

* [Filtering index statistics by metadata](/reference/api/2024-10/data-plane/describeindexstats)
* [Private endpoints](/guides/production/configure-private-endpoints)

  * This feature is available on AWS only.


# API versioning
Source: https://docs.pinecone.io/reference/api/versioning

Pinecone REST API: Pinecone's APIs are versioned to ensure that your applications continue to work as expected as the platform evolves.

Pinecone's APIs are versioned to ensure that your applications continue to work as expected as the platform evolves. Versions are named by release date in the format `YYYY-MM`, for example, `2025-10`.

## Release schedule

On a quarterly basis, Pinecone releases a new **stable** API version as well as a **release candidate** of the next stable version.

* **Stable:** Each stable version remains unchanged and supported for a minimum of 12 months. Since stable versions are released every 3 months, this means you have at least 9 months to test and migrate your app to the newest stable version before support for the previous version is removed.

* **Release candidate:** The release candidate gives you insight into the upcoming changes in the next stable version. It is available for approximately 3 months before the release of the stable version and can include new features, improvements, and [breaking changes](#breaking-changes).

Below is an example of Pinecone's release schedule:

<img />

<img />

## Specify an API version

<Warning>
  When using the API directly, it is important to specify an API version in your requests. If you don't, requests default to the oldest supported stable version. Once support for that version ends, your requests will default to the next oldest stable version, which could include breaking changes that require you to update your integration.
</Warning>

To specify an API version, set the `X-Pinecone-Api-Version` header to the version name.

For example, to use the latest stable version (`2026-04`) to describe an index, set the `X-Pinecone-Api-Version` header:

```shell curl theme={null}
PINECONE_API_KEY="YOUR_API_KEY"

curl -i -X GET "https://api.pinecone.io/indexes/movie-recommendations" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2026-04"
```

To use an older version, specify that version instead.

## SDK versions

Official [Pinecone SDKs](/reference/pinecone-sdks) provide convenient access to Pinecone APIs. SDK versions are pinned to specific API versions. When a new API version is released, a new version of the SDK is also released.

For the mapping between SDK and API versions, see [SDK versions](/reference/pinecone-sdks#sdk-versions).

## Breaking changes

Breaking changes are changes that can potentially break your integration with a Pinecone API. Breaking changes include:

* Removing an entire operation
* Removing or renaming a parameter
* Removing or renaming a response field
* Adding a new required parameter
* Making a previously optional parameter required
* Changing the type of a parameter or response field
* Removing enum values
* Adding a new validation rule to an existing parameter
* Changing authentication or authorization requirements

## Non-breaking changes

Non-breaking changes are additive and should not break your integration. Additive changes include:

* Adding an operation
* Adding an optional parameter
* Adding an optional request header
* Adding a response field
* Adding a response header
* Adding enum values

## Get updates

To ensure you always know about upcoming API changes, follow the [Release notes](/release-notes/).


# CLI authentication
Source: https://docs.pinecone.io/reference/cli/authentication

Authenticate the Pinecone CLI using user login, service accounts, or API keys, including auth priority and Admin API access rules.

This document describes how to authenticate the Pinecone CLI to manage your Pinecone resources.

## Authentication methods

| Method                              | Admin API | Control/data plane | Best for                         |
| ----------------------------------- | --------- | ------------------ | -------------------------------- |
| [User login](#user-login)           | ✅         | ✅                  | Interactive use                  |
| [Service account](#service-account) | ✅         | ✅                  | Automation with Admin API access |
| [API key](#api-key)                 | ❌         | ✅                  | Simple automation, CI/CD         |

### User login

Authenticate through a web browser. The token refreshes automatically and stays valid for up to 120 days (re-auth required after 30 days of inactivity).

```bash theme={null}
pc auth login
```

The CLI auto-targets your default organization and its first project. Change with `pc target -o "my-org" -p "my-project"`.

### Service account

Authenticate with credentials from a [service account](/guides/organizations/manage-service-accounts).

```bash theme={null}
pc auth configure --client-id "ID" --client-secret "SECRET"

# Or via environment variables
export PINECONE_CLIENT_ID="your-client-id"
export PINECONE_CLIENT_SECRET="your-client-secret"
```

The CLI auto-targets the service account's organization. For projects: auto-selects if one exists, prompts if multiple exist, or set manually with `pc target -p "my-project"`.

### API key

Authenticate with an [API key](/guides/projects/manage-api-keys). API keys can't access the Admin API.

```bash theme={null}
pc auth configure --api-key "YOUR_API_KEY"

# Or via environment variable
export PINECONE_API_KEY="your-api-key"
```

<Warning>
  API keys are scoped to a specific project. When set, control/data plane operations use the **key's project**, ignoring any [target context](/reference/cli/target-context) you've set.
</Warning>

## Auth priority

When multiple credentials exist, the CLI chooses based on operation type. Within each credential type, environment variables take precedence over stored configuration.

**Control/data plane operations:**

1. API key
2. User login token (via [managed keys](#managed-keys))
3. Service account (via [managed keys](#managed-keys))

**Admin API operations:**

1. User login token
2. Service account

<Note>
  User login and service account are mutually exclusive when configured via CLI commands—each clears the other. However, service account env vars don't clear a stored user login token.
</Note>

**Example scenarios:**

* If `PINECONE_API_KEY` is set, the CLI uses it for control/data plane operations, regardless of any stored API key.
* If you're logged in via `pc auth login` and also have `PINECONE_CLIENT_ID`/`PINECONE_CLIENT_SECRET` set, the user login token is used for everything—the service account env vars are ignored.
* If you have an API key configured and are also logged in, the API key is used for control/data plane operations, but user login is used for Admin API operations (since API keys can't access Admin API).

## Managed keys

When using user login or service account (without a default API key), the CLI automatically creates and manages API keys for control/data plane operations. This happens transparently on first use.

* **Stored locally:** `~/.config/pinecone/secrets.yaml` (permissions 0600)
* **Stored remotely:** Visible in console as `pinecone-cli-{id}` with origin `cli_created`

```bash theme={null}
# List locally tracked managed keys
pc auth local-keys list

# Delete managed keys (local + remote)
pc auth local-keys prune

# Delete only CLI-created managed keys
pc auth local-keys prune --origin cli

# Delete only user-created managed keys
pc auth local-keys prune --origin user

# Delete a specific API key by ID
pc api-key delete --id "KEY_ID"
```

<Note>
  When you run `pc api-key create --store` for a project that already has a CLI-created managed key, the CLI automatically deletes the old remote key before storing the new one.
</Note>

## Logging out

```bash theme={null}
pc auth logout
```

Clears all local auth data: tokens, credentials, API keys, managed keys, and [target context](/reference/cli/target-context).

<Note>
  `pc auth logout` doesn't delete managed keys from Pinecone's servers. Run `pc auth local-keys prune` first for full cleanup.
</Note>

## Local storage

Auth data is stored in `~/.config/pinecone/` with 0600 permissions:

| File           | Contents                                                         |
| -------------- | ---------------------------------------------------------------- |
| `secrets.yaml` | OAuth token, service account credentials, API keys, managed keys |
| `state.yaml`   | Target org/project                                               |
| `config.yaml`  | CLI settings (color, environment)                                |

## Check status

```bash theme={null}
pc auth status
```

Shows your current authentication method, target organization and project, token expiration (for user login), and environment configuration.


# CLI command reference
Source: https://docs.pinecone.io/reference/cli/command-reference

Complete Pinecone CLI command reference covering syntax, subcommands, flags, help output, and exit codes for auth, index, and project.

This document provides a complete reference for all Pinecone CLI commands.

## Command structure

The Pinecone CLI uses a hierarchical command structure. Each command consists of a primary command followed by one or more subcommands and optional flags.

```bash theme={null}
pc <command> <subcommand> [flags]
pc <command> <subcommand> <subcommand> [flags]
```

For example:

```bash theme={null}
# Top-level command with flags
pc target -o "organization-name" -p "project-name"

# Command (index) and subcommand (list)
pc index list

# Command (index) and subcommand (create) with flags
pc index create \
  --name my-index \
  --dimension 1536 \
  --metric cosine \
  --cloud aws \
  --region us-east-1

# Command (auth) and nested subcommands (local-keys prune) with flags
pc auth local-keys prune --id proj-abc123 --skip-confirmation
```

## Getting help

The CLI provides help for commands at every level:

```bash theme={null}
# top-level help
pc --help
pc -h

# command help
pc auth --help
pc index --help
pc project --help

# subcommmand help
pc index create --help
pc project create --help
pc auth configure --help

# nested subcommand help
pc auth local-keys prune --help
```

## Exit codes

All commands return exit code `0` for success and `1` for error.

## Available commands

This section describes all commands offered by the Pinecone CLI.

### Top-level commands

<AccordionGroup>
  <Accordion title="pc login (Authenticate via user login)">
    **Description**

    Authenticate via a web browser. After login, set a [target org and project](/reference/cli/target-context) with `pc target` before accessing data. This command defaults to an initial organization and project to which
    you have access (these values display in the terminal), but you can change them with `pc target`.

    **Usage**

    ```bash theme={null}
    pc login
    ```

    **Flags**

    None

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Log in via browser
    pc login

    # Then set target context
    pc target -o "my-org" -p "my-project"
    ```

    <Note>
      This is an alias for `pc auth login`. Both commands perform the same operation.
    </Note>
  </Accordion>

  <Accordion title="pc logout (Clear credentials / log out)">
    **Description**

    Clears all authentication data from local storage, including:

    * User login token
    * Service account credentials (client ID and secret)
    * Default (manually specified) API key
    * Locally managed keys (for all projects)
    * Target organization and project context

    **Usage**

    ```bash theme={null}
    pc logout
    ```

    **Flags**

    None

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Clear all credentials and context
    pc logout
    ```

    <Note>
      This is an alias for `pc auth logout`. Both commands perform the same operation. Does not delete managed API keys from Pinecone's servers. Run `pc auth local-keys prune` before logging out to fully clean up.
    </Note>
  </Accordion>

  <Accordion title="pc target (Set target organization and project)">
    **Description**

    Set the target organization and project for the CLI. Supports interactive organization and project selection or direct specification via flags.  For details, see [CLI target context](/reference/cli/target-context).

    **Usage**

    ```bash theme={null}
    pc target [flags]
    ```

    **Flags**

    | Long flag           | Short flag | Description                    |
    | :------------------ | :--------- | :----------------------------- |
    | `--clear`           |            | Clear target context           |
    | `--json`            | `-j`       | Output in JSON format          |
    | `--org`             | `-o`       | Organization name              |
    | `--organization-id` |            | Organization ID                |
    | `--project`         | `-p`       | Project name                   |
    | `--project-id`      |            | Project ID                     |
    | `--show`            | `-s`       | Display current target context |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Interactive targeting after login
    pc login
    pc target

    # Set specific organization and project
    pc target -o "my-org" -p "my-project"

    # Show current context
    pc target --show

    # Clear all context
    pc target --clear
    ```
  </Accordion>

  <Accordion title="pc version (Show CLI version)">
    **Description**

    Displays version information for the CLI, including the version number, commit SHA, and build date.

    **Usage**

    ```bash theme={null}
    pc version
    ```

    **Flags**

    None

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Display version information
    pc version
    ```
  </Accordion>

  <Accordion title="pc whoami (Show current user)">
    **Description**

    Displays information about the currently authenticated user. To use this command, you must be authenticated via user login.

    **Usage**

    ```bash theme={null}
    pc whoami
    ```

    **Flags**

    None

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    pc whoami
    ```

    <Note>
      This is an alias for `pc auth whoami`. Both commands perform the same operation.
    </Note>
  </Accordion>
</AccordionGroup>

### Authentication

<AccordionGroup>
  <Accordion title="pc auth clear (Clear specific credentials)">
    **Description**

    Selectively clears specific authentication data without affecting other credentials. At least one flag is required.

    **Usage**

    ```bash theme={null}
    pc auth clear [flags]
    ```

    **Flags**

    | Long flag           | Short flag | Description                                         |
    | :------------------ | :--------- | :-------------------------------------------------- |
    | `--api-key`         |            | Clear only the default (manually specified) API key |
    | `--service-account` |            | Clear only service account credentials              |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Clear only the default (manually specified) API key
    pc auth clear --api-key
    pc auth status

    # Clear service account
    pc auth clear --service-account
    ```

    <Note>
      More surgical than `pc auth logout`. Does not clear user login token or managed keys. For those, use `pc auth logout` or `pc auth local-keys prune`.
    </Note>
  </Accordion>

  <Accordion title="pc auth configure (Configure service account or API key)">
    **Description**

    Configures service account credentials or a default (manually specified) API key.

    Service accounts automatically target the organization and prompt for project selection, unless there is only one project. A default API key overrides any previously specified target organization/project context. When setting a service account, this operation clears the user login token, if one exists.
    For details, see [CLI target context](/reference/cli/target-context).

    **Usage**

    ```bash theme={null}
    pc auth configure [flags]
    ```

    **Flags**

    | Long flag               | Short flag | Description                                          |
    | :---------------------- | :--------- | :--------------------------------------------------- |
    | `--api-key`             |            | Default API key to use for authentication            |
    | `--client-id`           |            | Service account client ID                            |
    | `--client-secret`       |            | Service account client secret                        |
    | `--client-secret-stdin` |            | Read client secret from stdin                        |
    | `--json`                | `-j`       | Output in JSON format                                |
    | `--project-id`          | `-p`       | Target project ID (optional, interactive if omitted) |
    | `--prompt-if-missing`   |            | Prompt for missing credentials                       |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Service account setup (auto-targets org and prompts for project)
    pc auth configure --client-id my-id --client-secret my-secret

    # Service account with specific project
    pc auth configure \
      --client-id my-id \
      --client-secret my-secret \
      -p proj-123

    # Default API key (overrides any target context)
    pc auth configure --api-key pcsk_abc123
    ```

    <Note>
      `pc auth configure --api-key "YOUR_API_KEY"` does the same thing as `pc config set-api-key "YOUR_API_KEY"`. To learn about targeting a project after authenticating with a service account, see [CLI target context](/reference/cli/target-context).
    </Note>
  </Accordion>

  <Accordion title="pc auth local-keys list (List managed keys)">
    **Description**

    Displays all [managed API keys](/reference/cli/authentication#managed-keys) stored locally by the CLI, with various details.

    **Usage**

    ```bash theme={null}
    pc auth local-keys list [flags]
    ```

    **Flags**

    | Long flag  | Short flag | Description                                |
    | :--------- | :--------- | :----------------------------------------- |
    | `--json`   | `-j`       | Output in JSON format                      |
    | `--reveal` |            | Show the actual API key values (sensitive) |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # List all locally managed keys
    pc auth local-keys list

    # Show key values
    pc auth local-keys list --reveal

    # After storing a key
    pc api-key create -n "my-key" --store
    pc auth local-keys list
    ```
  </Accordion>

  <Accordion title="pc auth local-keys prune (Delete managed keys)">
    **Description**

    Deletes locally stored [managed API keys](/reference/cli/authentication#managed-keys) from local storage and Pinecone's servers. Filters by origin (`cli`/`user`/`all`) or project ID.

    **Usage**

    ```bash theme={null}
    pc auth local-keys prune [flags]
    ```

    **Flags**

    | Long flag             | Short flag | Description                                                 |
    | :-------------------- | :--------- | :---------------------------------------------------------- |
    | `--dry-run`           |            | Preview deletions without applying                          |
    | `--id`                |            | Prune keys for specific project ID only                     |
    | `--json`              | `-j`       | Output in JSON format                                       |
    | `--origin`            | `-o`       | Filter by origin - `cli`, `user`, or `all` (default: `all`) |
    | `--skip-confirmation` |            | Skip confirmation prompt                                    |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Preview deletions
    pc auth local-keys prune --dry-run

    # Delete CLI-created keys only
    pc auth local-keys prune -o cli --skip-confirmation

    # Delete for specific project
    pc auth local-keys prune --id proj-abc123

    # Before/after check
    pc auth local-keys list
    pc auth local-keys prune -o cli
    pc auth local-keys list
    ```

    <Note>
      This deletes keys from both local storage and Pinecone servers. Use `--dry-run` to preview before committing.
    </Note>
  </Accordion>

  <Accordion title="pc auth login (Authenticate via user login)">
    **Description**

    Authenticate via user login in the web browser. After login, [set a target org and project](/reference/cli/target-context).

    **Usage**

    ```bash theme={null}
    pc auth login
    pc login  # shorthand
    ```

    **Flags**

    None

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Login and set target
    pc auth login
    pc target -o "my-org" -p "my-project"
    pc index list
    ```

    <Note>
      Tokens refresh automatically and remain valid for up to 120 days. If you're inactive for more than 30 days, you must re-authenticate. Logging in clears any existing service account credentials. This command does the same thing as `pc login`.
    </Note>
  </Accordion>

  <Accordion title="pc auth logout (Clear authentication credentials)">
    **Description**

    Clears all authentication data from local storage, including:

    * User login token
    * Service account credentials (client ID and secret)
    * Default (manually specified) API key
    * Locally managed keys (for all projects)
    * Target organization and project context

    **Usage**

    ```bash theme={null}
    pc auth logout
    ```

    **Flags**

    None

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Clear all credentials and context
    pc auth logout
    ```

    <Note>
      This command does the same thing as `pc logout`. Does not delete managed API keys from Pinecone's servers. Run `pc auth local-keys prune` before logging out to fully clean up.
    </Note>
  </Accordion>

  <Accordion title="pc auth status (Show authentication status)">
    **Description**

    Shows details about all configured authentication methods.

    **Usage**

    ```bash theme={null}
    pc auth status [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description           |
    | :-------- | :--------- | :-------------------- |
    | `--json`  | `-j`       | Output in JSON format |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Check status after login
    pc auth login
    pc auth status

    # JSON output for scripting
    pc auth status --json
    ```
  </Accordion>

  <Accordion title="pc auth whoami (Show current user information)">
    **Description**

    Displays information about the currently authenticated user. To use this command, you must be authenticated via user login.

    **Usage**

    ```bash theme={null}
    pc auth whoami
    ```

    **Flags**

    None

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    pc auth whoami
    ```

    <Note>
      This command does the same thing as `pc whoami`.
    </Note>
  </Accordion>
</AccordionGroup>

### Indexes

<AccordionGroup>
  <Accordion title="pc index configure (Update index configuration)">
    **Description**

    Modifies the configuration of an existing index.

    **Usage**

    ```bash theme={null}
    pc index configure [flags]
    ```

    **Flags**

    | Long flag                | Short flag | Description                                                     |
    | :----------------------- | :--------- | :-------------------------------------------------------------- |
    | `--index-name`           | `-i`       | Name of index to configure (required)                           |
    | `--deletion-protection`  |            | Enable or disable deletion protection - `enabled` or `disabled` |
    | `--tags`                 |            | Custom user tags (key=value pairs)                              |
    | `--json`                 | `-j`       | Output in JSON format                                           |
    | **Dedicated read nodes** |            |                                                                 |
    | `--read-mode`            |            | Read capacity mode - `ondemand` or `dedicated`                  |
    | `--read-node-type`       |            | Node type for dedicated read - `b1` or `t1`                     |
    | `--read-shards`          |            | Number of shards for dedicated read capacity                    |
    | `--read-replicas`        |            | Number of replicas for dedicated read capacity                  |
    | **Integrated embedding** |            |                                                                 |
    | `--model`                |            | Embedding model name                                            |
    | `--field-map`            |            | Field mapping for embedding (key=value pairs)                   |
    | `--read-parameters`      |            | Read parameters for embedding model (key=value pairs)           |
    | `--write-parameters`     |            | Write parameters for embedding model (key=value pairs)          |
    | **Pods**                 |            |                                                                 |
    | `--pod-type`             | `-t`       | Type of pod to use; can only upgrade when configuring           |
    | `--replicas`             | `-r`       | Number of replicas of the index to configure                    |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Enable deletion protection
    pc index configure --index-name my-index --deletion-protection enabled

    # Add tags
    pc index configure --index-name my-index --tags environment=production,team=ml

    # Switch to dedicated read capacity
    pc index configure --index-name my-index \
      --read-mode dedicated \
      --read-node-type b1 \
      --read-shards 2 \
      --read-replicas 2

    # Verify changes
    pc index describe --index-name my-index
    ```

    <Note>
      Configuration changes may take some time to take effect.
    </Note>
  </Accordion>

  <Accordion title="pc index create (Create a new index)">
    **Description**

    Creates a new index in your Pinecone project. Supports serverless, pod-based, integrated (with embedding model), and BYOC (Bring Your Own Cloud) index types.

    **Usage**

    ```bash theme={null}
    pc index create [flags]
    ```

    **Flags**

    | Long flag                | Short flag | Description                                                                    |
    | :----------------------- | :--------- | :----------------------------------------------------------------------------- |
    | `--name`                 | `-n`       | Index name (required)                                                          |
    | `--dimension`            | `-d`       | Vector dimension (required for standard indexes, optional for integrated)      |
    | `--metric`               | `-m`       | Similarity metric - `cosine`, `euclidean`, or `dotproduct` (default: `cosine`) |
    | `--cloud`                | `-c`       | Cloud provider - `aws`, `gcp`, or `azure`                                      |
    | `--region`               | `-r`       | Cloud region                                                                   |
    | `--vector-type`          | `-v`       | Vector type - `dense` or `sparse` (serverless only)                            |
    | `--source-collection`    |            | Name of the source collection from which to create the index                   |
    | `--schema`               |            | Metadata schema to control which fields are indexed (comma-separated)          |
    | `--deletion-protection`  |            | Deletion protection - `enabled` or `disabled`                                  |
    | `--tags`                 |            | Custom user tags (key=value pairs)                                             |
    | `--json`                 | `-j`       | Output in JSON format                                                          |
    | **Integrated indexes**   |            |                                                                                |
    | `--model`                |            | Integrated embedding model name                                                |
    | `--field-map`            |            | Field mapping for integrated embedding (key=value pairs)                       |
    | `--read-parameters`      |            | Read parameters for embedding model (key=value pairs)                          |
    | `--write-parameters`     |            | Write parameters for embedding model (key=value pairs)                         |
    | **BYOC indexes**         |            |                                                                                |
    | `--byoc-environment`     |            | BYOC environment to use for the index                                          |
    | **Dedicated read nodes** |            |                                                                                |
    | `--read-mode`            |            | Read capacity mode - `ondemand` or `dedicated` (default: `ondemand`)           |
    | `--read-node-type`       |            | Node type for dedicated read - `b1` or `t1`                                    |
    | `--read-shards`          |            | Number of shards (each shard provides 250 GB storage)                          |
    | `--read-replicas`        |            | Number of replicas for higher throughput                                       |
    | **Pod-based indexes**    |            |                                                                                |
    | `--environment`          |            | Environment of the index to create (for example, `us-east-1-aws`)              |
    | `--pod-type`             |            | Type of pod to use (for example, `p1.x1`, `s1.x2`)                             |
    | `--shards`               |            | Number of shards (default: `1`)                                                |
    | `--replicas`             |            | Number of replicas (default: `1`)                                              |
    | `--metadata-config`      |            | Comma-separated list of metadata fields to index for search                    |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Create serverless index
    pc index create -n my-index -d 1536 -m cosine -c aws -r us-east-1

    # Create sparse vector index
    pc index create -n sparse-index -m dotproduct -c aws -r us-east-1 --vector-type sparse

    # With integrated embedding model
    pc index create \
      -n my-index \
      -m cosine \
      -c aws \
      -r us-east-1 \
      --model multilingual-e5-large \
      --field-map text=chunk_text

    # With dedicated read capacity
    pc index create \
      -n my-index \
      -d 1536 \
      -m cosine \
      -c aws \
      -r us-east-1 \
      --read-mode dedicated \
      --read-node-type b1 \
      --read-shards 2 \
      --read-replicas 2

    # With deletion protection
    pc index create \
      -n my-index \
      -d 1536 \
      -m cosine \
      -c aws \
      -r us-west-2 \
      --deletion-protection enabled

    # From collection
    pc index create \
      -n my-index \
      -d 1536 \
      -m cosine \
      -c aws \
      -r eu-west-1 \
      --source-collection my-collection

    # Create pod-based index
    pc index create \
      -n my-index \
      -d 1536 \
      -m cosine \
      --environment us-east-1-aws \
      --pod-type p1.x1 \
      --shards 1 \
      --replicas 1
    ```

    <Note>
      For a list of valid regions for a serverless index, see [Create a serverless index](/guides/index-data/create-an-index).
    </Note>
  </Accordion>

  <Accordion title="pc index delete (Delete an index)">
    **Description**

    Permanently deletes an index and all its data. This operation cannot be undone.

    **Usage**

    ```bash theme={null}
    pc index delete [flags]
    ```

    **Flags**

    | Long flag             | Short flag | Description                                                |
    | :-------------------- | :--------- | :--------------------------------------------------------- |
    | `--index-name`        | `-i`       | Name of index to delete (required)                         |
    | `--skip-confirmation` |            | Skip the deletion confirmation prompt                      |
    | `--json`              | `-j`       | Output in JSON format (also skips the confirmation prompt) |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Delete an index (prompts for confirmation)
    pc index delete --index-name my-index

    # Skip the confirmation prompt
    pc index delete --index-name my-index --skip-confirmation

    # List before and after
    pc index list
    pc index delete --index-name test-index --skip-confirmation
    pc index list
    ```

    <Note>
      This command prompts for confirmation before deleting. Pass `--skip-confirmation` (or `--json`) to bypass the prompt in non-interactive contexts.
    </Note>
  </Accordion>

  <Accordion title="pc index describe (Show index details)">
    **Description**

    Displays detailed configuration and status information for a specific index.

    **Usage**

    ```bash theme={null}
    pc index describe [flags]
    ```

    **Flags**

    | Long flag      | Short flag | Description           |
    | :------------- | :--------- | :-------------------- |
    | `--index-name` | `-i`       | Index name (required) |
    | `--json`       | `-j`       | Output in JSON format |

    The `--name`/`-n` flag is a deprecated alias for `--index-name`/`-i`.

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Describe an index
    pc index describe -i my-index

    # JSON output
    pc index describe -i my-index -j

    # Check newly created index
    pc index create -n test-index -d 1536 -m cosine -c aws -r us-east-1
    pc index describe -i test-index
    ```
  </Accordion>

  <Accordion title="pc index stats (Show index statistics)">
    **Description**

    Displays statistics for an index, including total vector count and namespace breakdown. Optionally filter results with a metadata filter.

    **Usage**

    ```bash theme={null}
    pc index stats [flags]
    ```

    **Flags**

    | Long flag      | Short flag | Description                                                    |
    | :------------- | :--------- | :------------------------------------------------------------- |
    | `--index-name` | `-i`       | Index name (required)                                          |
    | `--filter`     | `-f`       | Metadata filter (inline JSON, `./path.json`, or `-` for stdin) |
    | `--json`       | `-j`       | Output in JSON format                                          |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Get stats for an index
    pc index stats -i my-index

    # Get stats with a metadata filter
    pc index stats -i my-index --filter '{"genre":{"$eq":"rock"}}'

    # Filter from file
    pc index stats -i my-index --filter ./filter.json

    # JSON output
    pc index stats -i my-index -j
    ```
  </Accordion>

  <Accordion title="pc index list (List all indexes)">
    **Description**

    Displays all indexes in your current target project, including various details.

    **Usage**

    ```bash theme={null}
    pc index list [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description                                         |
    | :-------- | :--------- | :-------------------------------------------------- |
    | `--json`  | `-j`       | Output in JSON format (includes full index details) |
    | `--wide`  | `-w`       | Show additional columns (host, embed, tags)         |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # List all indexes
    pc index list

    # Show additional details
    pc index list --wide

    # JSON output for scripting
    pc index list -j

    # After creating indexes
    pc index create -n test-1 -d 768 -m cosine -c aws -r us-east-1
    pc index list
    ```
  </Accordion>
</AccordionGroup>

### Namespaces

<AccordionGroup>
  <Accordion title="pc index namespace create (Create a namespace)">
    **Description**

    Creates a new namespace within an index. Namespaces allow you to partition vectors within an index.

    **Usage**

    ```bash theme={null}
    pc index namespace create [flags]
    ```

    **Flags**

    | Long flag      | Short flag | Description                                         |
    | :------------- | :--------- | :-------------------------------------------------- |
    | `--index-name` | `-i`       | Index name (required)                               |
    | `--name`       |            | Namespace name (required)                           |
    | `--schema`     |            | Metadata schema for the namespace (comma-separated) |
    | `--json`       | `-j`       | Output in JSON format                               |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Create a namespace
    pc index namespace create -i my-index --name tenant-a

    # Create with metadata schema (comma-separated list of filterable metadata fields)
    pc index namespace create -i my-index --name tenant-b --schema "category,brand"

    # JSON output
    pc index namespace create -i my-index --name tenant-c -j
    ```
  </Accordion>

  <Accordion title="pc index namespace delete (Delete a namespace)">
    **Description**

    Deletes a namespace and all its vectors from an index. This operation cannot be undone.

    **Usage**

    ```bash theme={null}
    pc index namespace delete [flags]
    ```

    **Flags**

    | Long flag             | Short flag | Description                                                            |
    | :-------------------- | :--------- | :--------------------------------------------------------------------- |
    | `--index-name`        | `-i`       | Index name (required)                                                  |
    | `--name`              |            | Namespace name (required); use `__default__` for the default namespace |
    | `--skip-confirmation` |            | Skip the deletion confirmation prompt                                  |
    | `--json`              | `-j`       | Output in JSON format (also skips the confirmation prompt)             |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Delete a namespace (prompts for confirmation)
    pc index namespace delete -i my-index --name tenant-a

    # Delete the default namespace
    pc index namespace delete -i my-index --name __default__

    # Skip the confirmation prompt
    pc index namespace delete -i my-index --name tenant-a --skip-confirmation
    ```

    <Warning>
      Deleting a namespace removes all vectors in that namespace. This operation cannot be undone.
    </Warning>
  </Accordion>

  <Accordion title="pc index namespace describe (Show namespace details)">
    **Description**

    Displays detailed information about a specific namespace, including record count and schema configuration.

    **Usage**

    ```bash theme={null}
    pc index namespace describe [flags]
    ```

    **Flags**

    | Long flag      | Short flag | Description                                                            |
    | :------------- | :--------- | :--------------------------------------------------------------------- |
    | `--index-name` | `-i`       | Index name (required)                                                  |
    | `--name`       |            | Namespace name (required); use `__default__` for the default namespace |
    | `--json`       | `-j`       | Output in JSON format                                                  |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Describe a namespace
    pc index namespace describe -i my-index --name tenant-a

    # Describe the default namespace
    pc index namespace describe -i my-index --name __default__

    # JSON output
    pc index namespace describe -i my-index --name tenant-a -j
    ```
  </Accordion>

  <Accordion title="pc index namespace list (List namespaces)">
    **Description**

    Lists all namespaces within an index, including vector counts.

    **Usage**

    ```bash theme={null}
    pc index namespace list [flags]
    ```

    **Flags**

    | Long flag            | Short flag | Description                    |
    | :------------------- | :--------- | :----------------------------- |
    | `--index-name`       | `-i`       | Index name (required)          |
    | `--limit`            | `-l`       | Maximum number of results      |
    | `--pagination-token` | `-p`       | Pagination token for next page |
    | `--prefix`           |            | Filter namespaces by prefix    |
    | `--json`             | `-j`       | Output in JSON format          |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # List all namespaces
    pc index namespace list -i my-index

    # Filter by prefix
    pc index namespace list -i my-index --prefix "tenant-"

    # Limit results
    pc index namespace list -i my-index --limit 10

    # JSON output
    pc index namespace list -i my-index -j
    ```
  </Accordion>
</AccordionGroup>

### Vectors

<AccordionGroup>
  <Accordion title="pc index vector delete (Delete vectors)">
    **Description**

    Deletes vectors from an index by ID, filter, or deletes all vectors in a namespace.

    **Usage**

    ```bash theme={null}
    pc index vector delete [flags]
    ```

    **Flags**

    | Long flag             | Short flag | Description                                                               |
    | :-------------------- | :--------- | :------------------------------------------------------------------------ |
    | `--index-name`        | `-i`       | Index name (required)                                                     |
    | `--namespace`         |            | Namespace to delete from (default: `__default__`)                         |
    | `--ids`               |            | Vector IDs to delete (inline JSON array, `./path.json`, or `-` for stdin) |
    | `--filter`            |            | Metadata filter (inline JSON, `./path.json`, or `-` for stdin)            |
    | `--all-vectors`       |            | Delete all vectors in the namespace                                       |
    | `--skip-confirmation` |            | Skip the confirmation prompt shown for `--all-vectors`                    |
    | `--json`              | `-j`       | Output in JSON format (also skips the confirmation prompt)                |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Delete specific vectors
    pc index vector delete -i my-index --ids '["id1"]'

    # Delete multiple vectors (inline JSON array, or JSON array in a file)
    pc index vector delete -i my-index --ids '["id1", "id2"]'

    # Delete by filter
    pc index vector delete -i my-index --filter '{"genre":"classical"}'

    # Delete all vectors in a namespace (prompts for confirmation)
    pc index vector delete -i my-index --namespace old-data --all-vectors

    # Delete all vectors without the prompt
    pc index vector delete -i my-index --namespace old-data --all-vectors --skip-confirmation
    ```

    <Note>
      Only `--all-vectors` prompts for confirmation. Targeted deletes with `--ids` or `--filter` proceed without a prompt. Pass `--skip-confirmation` (or `--json`) to bypass the `--all-vectors` prompt.
    </Note>

    <Warning>
      Vector deletion is permanent and cannot be undone.
    </Warning>
  </Accordion>

  <Accordion title="pc index vector fetch (Fetch vectors by ID or filter)">
    **Description**

    Retrieves vectors by their IDs or by a metadata filter, returning the vector values and metadata.

    **Usage**

    ```bash theme={null}
    pc index vector fetch [flags]
    ```

    **Flags**

    | Long flag            | Short flag | Description                                                              |
    | :------------------- | :--------- | :----------------------------------------------------------------------- |
    | `--index-name`       | `-i`       | Index name (required)                                                    |
    | `--namespace`        |            | Namespace to fetch from (default: `__default__`)                         |
    | `--ids`              |            | Vector IDs to fetch (inline JSON array, `./path.json`, or `-` for stdin) |
    | `--filter`           | `-f`       | Metadata filter (inline JSON, `./path.json`, or `-` for stdin)           |
    | `--limit`            | `-l`       | Maximum number of vectors to fetch                                       |
    | `--pagination-token` | `-p`       | Pagination token for next page                                           |
    | `--body`             |            | Request body JSON (inline, `./path.json`, or `-` for stdin)              |
    | `--json`             | `-j`       | Output in JSON format                                                    |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Fetch specific vectors by ID
    pc index vector fetch -i my-index --ids '["123","456","789"]'

    # Fetch from a file
    pc index vector fetch -i my-index --ids ./ids.json

    # Fetch by metadata filter
    pc index vector fetch -i my-index --filter '{"genre":{"$eq":"rock"}}'

    # Fetch from a namespace
    pc index vector fetch -i my-index --namespace tenant-a --ids '["doc-123"]'

    # JSON output
    pc index vector fetch -i my-index --ids '["vec1"]' -j
    ```

    <Note>
      Use either `--ids` or `--filter`, not both. When using `--ids`, pagination flags are not applicable.
    </Note>
  </Accordion>

  <Accordion title="pc index vector list (List vector IDs)">
    **Description**

    Lists vector IDs in a namespace with optional pagination.

    **Usage**

    ```bash theme={null}
    pc index vector list [flags]
    ```

    **Flags**

    | Long flag            | Short flag | Description                                     |
    | :------------------- | :--------- | :---------------------------------------------- |
    | `--index-name`       | `-i`       | Index name (required)                           |
    | `--namespace`        |            | Namespace to list from (default: `__default__`) |
    | `--limit`            | `-l`       | Maximum number of IDs to return                 |
    | `--pagination-token` | `-p`       | Pagination token for next page                  |
    | `--json`             | `-j`       | Output in JSON format                           |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # List vector IDs
    pc index vector list -i my-index

    # List from a namespace with limit
    pc index vector list -i my-index --namespace tenant-a --limit 50

    # JSON output
    pc index vector list -i my-index -j
    ```
  </Accordion>

  <Accordion title="pc index vector query (Query vectors)">
    **Description**

    Queries an index for similar vectors using dense vectors, sparse vectors, or vector ID.

    **Usage**

    ```bash theme={null}
    pc index vector query [flags]
    ```

    **Flags**

    | Long flag            | Short flag | Description                                                                       |
    | :------------------- | :--------- | :-------------------------------------------------------------------------------- |
    | `--index-name`       | `-i`       | Index name (required)                                                             |
    | `--namespace`        |            | Namespace to query (default: `__default__`)                                       |
    | `--id`               |            | Query by vector ID                                                                |
    | `--vector`           | `-v`       | Query vector values (inline JSON array, `./path.json`, or `-` for stdin)          |
    | `--sparse-indices`   |            | Sparse vector indices (inline JSON uint32 array, `./path.json`, or `-` for stdin) |
    | `--sparse-values`    |            | Sparse vector values (inline JSON array, `./path.json`, or `-` for stdin)         |
    | `--top-k`            | `-k`       | Number of results to return (default: 10)                                         |
    | `--filter`           | `-f`       | Metadata filter (inline JSON, `./path.json`, or `-` for stdin)                    |
    | `--include-values`   |            | Include vector values in results                                                  |
    | `--include-metadata` |            | Include metadata in results                                                       |
    | `--body`             |            | Request body JSON (inline, `./path.json`, or `-` for stdin)                       |
    | `--json`             | `-j`       | Output in JSON format                                                             |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Query by vector ID
    pc index vector query -i my-index --id "doc-123" -k 10 --include-metadata

    # Query by vector values
    pc index vector query -i my-index --vector '[0.1, 0.2, 0.3]' -k 25

    # Query with metadata filter
    pc index vector query -i my-index \
      --vector '[0.1, 0.2, 0.3]' \
      --filter '{"genre":{"$eq":"sci-fi"}}' \
      --include-metadata

    # Query from file (file contains a JSON array that specifies the query vector)
    pc index vector query -i my-index --vector ./embedding.json -k 20

    # Query with sparse vectors (inline)
    pc index vector query -i my-index \
      --sparse-indices '[0, 5, 12]' \
      --sparse-values '[0.5, 0.3, 0.8]' \
      -k 15

    # Query with sparse vectors from files
    # indices.json: [0, 5, 12]
    # values.json: [0.5, 0.3, 0.8]
    pc index vector query -i my-index \
      --sparse-indices ./indices.json \
      --sparse-values ./values.json \
      -k 15

    # Query from stdin (extract embedding from a document)
    # doc.json: {"id": "doc-123", "embedding": [0.1, 0.2, 0.3], "text": "..."}
    jq -c '.embedding' doc.json | pc index vector query -i my-index --vector - -k 10
    ```

    <Note>
      Use `--id`, `--vector`, or sparse vectors (`--sparse-indices` and `--sparse-values`) to specify what to query against. These options are mutually exclusive.
    </Note>
  </Accordion>

  <Accordion title="pc index vector update (Update vectors)">
    **Description**

    Updates a vector's values, sparse values, or metadata by ID, or updates metadata for multiple vectors matching a filter.

    **Usage**

    ```bash theme={null}
    pc index vector update [flags]
    ```

    **Flags**

    | Long flag          | Short flag | Description                                                                    |
    | :----------------- | :--------- | :----------------------------------------------------------------------------- |
    | `--index-name`     | `-i`       | Index name (required)                                                          |
    | `--namespace`      |            | Namespace containing the vector (default: `__default__`)                       |
    | `--id`             |            | Vector ID to update                                                            |
    | `--values`         |            | New vector values (inline JSON array, `./path.json`, or `-` for stdin)         |
    | `--sparse-indices` |            | New sparse indices (inline JSON uint32 array, `./path.json`, or `-` for stdin) |
    | `--sparse-values`  |            | New sparse values (inline JSON array, `./path.json`, or `-` for stdin)         |
    | `--metadata`       |            | New or updated metadata (inline JSON, `./path.json`, or `-` for stdin)         |
    | `--filter`         |            | Metadata filter for bulk update (inline JSON, `./path.json`, or `-` for stdin) |
    | `--dry-run`        |            | Preview how many records would be updated without applying changes             |
    | `--body`           |            | Request body JSON (inline, `./path.json`, or `-` for stdin)                    |
    | `--json`           | `-j`       | Output in JSON format                                                          |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Update metadata for a single vector
    pc index vector update -i my-index --id "vec1" --metadata '{"category":"updated"}'

    # Update values for a single vector
    pc index vector update -i my-index --id "vec1" --values '[0.2, 0.3, 0.4]'

    # Update sparse values
    # indices.json: [0, 5, 12]
    # values.json: [0.5, 0.3, 0.8]
    pc index vector update -i my-index --id "vec1" \
      --sparse-indices ./indices.json \
      --sparse-values ./values.json

    # Bulk update metadata by filter (preview first)
    pc index vector update -i my-index \
      --filter '{"genre":{"$eq":"sci-fi"}}' \
      --metadata '{"genre":"fantasy"}' \
      --dry-run

    # Apply the bulk update
    pc index vector update -i my-index \
      --filter '{"genre":{"$eq":"sci-fi"}}' \
      --metadata '{"genre":"fantasy"}'
    ```

    <Note>
      Use either `--id` for single vector updates or `--filter` for bulk updates. These options are mutually exclusive.
    </Note>
  </Accordion>

  <Accordion title="pc index vector upsert (Upsert vectors)">
    **Description**

    Inserts or updates vectors in an index from a JSON or JSONL file, or inline JSON. The CLI automatically batches vectors for efficient uploading. Files can contain any number of vectors—the CLI splits them into batches and sends multiple API requests as needed.

    **Usage**

    ```bash theme={null}
    pc index vector upsert [flags]
    ```

    **Flags**

    | Long flag      | Short flag | Description                                                                        |
    | :------------- | :--------- | :--------------------------------------------------------------------------------- |
    | `--index-name` | `-i`       | Index name (required)                                                              |
    | `--namespace`  |            | Namespace to upsert into (default: `__default__`)                                  |
    | `--body`       |            | Request body JSON or JSONL (inline, `./path.json[l]`, or `-` for stdin) (required) |
    | `--batch-size` | `-b`       | Size of batches to upsert (default: 500)                                           |
    | `--json`       | `-j`       | Output in JSON format                                                              |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Upsert from JSON file (with "vectors" array)
    # vectors.json: {"vectors": [{"id": "vec1", "values": [0.1, 0.2, 0.3], "metadata": {"genre": "comedy"}}]}
    pc index vector upsert -i my-index --body ./vectors.json

    # Upsert with inline JSON
    pc index vector upsert -i my-index --body '{"vectors": [{"id": "vec1", "values": [0.1, 0.2, 0.3], "metadata": {"genre": "comedy"}}]}'

    # Upsert from JSONL file (one vector per line)
    # vectors.jsonl: {"id": "vec1", "values": [0.1, 0.2, 0.3]}
    #                {"id": "vec2", "values": [0.4, 0.5, 0.6]}
    pc index vector upsert -i my-index --body ./vectors.jsonl

    # Upsert from stdin (same format as JSON or JSONL file)
    cat vectors.json | pc index vector upsert -i my-index --body -

    # Custom batch size (default: 500, max: 1000 per API request)
    pc index vector upsert -i my-index --body ./vectors.json --batch-size 1000
    ```

    <Note>
      **Batch size limits:** The API accepts up to 1000 vectors per request. The CLI defaults to batches of 500 vectors, but you can adjust this with `--batch-size` (up to 1000). Large files are automatically split into multiple batches.

      **File size:** There's no explicit file size limit—the CLI reads the entire file into memory and batches it automatically. Very large files are supported as long as they fit in available system memory.
    </Note>
  </Accordion>
</AccordionGroup>

### Records

<AccordionGroup>
  <Accordion title="pc index record search (Search records in an index)">
    **Description**

    Search an index namespace with a query text, query vector, or record ID and return the most similar records, along with their similarity scores. Optionally, rerank the initial results based on their relevance to the query.

    Searching with text is supported only for indexes with an integrated embedding configured. Searching with a query vector or record ID is supported for all indexes.

    Exactly one primary query mode must be provided:

    * `--inputs` — query text (requires an index with integrated embedding)
    * `--id` — use an existing record's vector as the query
    * `--vector` — provide a dense vector directly (all index types)
    * `--sparse-indices` + `--sparse-values` — sparse vector (all index types)

    Combine `--vector` with `--sparse-indices`/`--sparse-values` for hybrid search. Use `--body` to pass a full request object; flags take precedence over `--body` when both specify the same field.

    **Usage**

    ```bash theme={null}
    pc index record search [flags]
    ```

    **Flags**

    | Long flag          | Short flag | Description                                                                                                                                                     |
    | :----------------- | :--------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `--index-name`     | `-i`       | Name of the index to search (required)                                                                                                                          |
    | `--inputs`         |            | Query inputs for text search (inline JSON, `./path.json`, or `-` for stdin); requires integrated embedding. Mutually exclusive with `--id` and `--vector`.      |
    | `--id`             |            | Use an existing record's vector by ID for the query. Mutually exclusive with `--inputs` and `--vector`.                                                         |
    | `--vector`         | `-v`       | Dense vector values to search against (inline JSON float32 array, `./path.json`, or `-` for stdin). Mutually exclusive with `--inputs` and `--id`.              |
    | `--sparse-indices` |            | Sparse vector indices (inline JSON int32 array, `./path.json`, or `-` for stdin). Must be used together with `--sparse-values`.                                 |
    | `--sparse-values`  |            | Sparse vector values (inline JSON float32 array, `./path.json`, or `-` for stdin). Must be used together with `--sparse-indices`.                               |
    | `--top-k`          | `-k`       | Number of results to return (required)                                                                                                                          |
    | `--namespace`      |            | Namespace to search                                                                                                                                             |
    | `--filter`         |            | Metadata filter (inline JSON, `./path.json`, or `-` for stdin)                                                                                                  |
    | `--rerank`         |            | Re-score results using an inference model (inline JSON, `./path.json`, or `-` for stdin). Required fields: `model` (string), `rank_fields` (string array).      |
    | `--match-terms`    |            | Keyword terms filter for sparse integrated indexes (inline JSON, `./path.json`, or `-` for stdin). Required field: `terms` (string array). Requires `--inputs`. |
    | `--fields`         |            | Fields to return in results (inline JSON string array, `./path.json`, or `-` for stdin)                                                                         |
    | `--body`           |            | Full request body JSON (inline, `./path.json`, or `-` for stdin). Flags take precedence when both specify the same field.                                       |
    | `--json`           | `-j`       | Output in JSON format                                                                                                                                           |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Examples**

    ```bash theme={null}
    # Text search (integrated embedding indexes only)
    pc index record search --index-name my-index --inputs '{"text":"disease prevention"}' --top-k 10
    pc index record search --index-name my-index --inputs '{"text":"disease prevention"}' --namespace my-namespace --top-k 5
    pc index record search --index-name my-index --inputs '{"text":"disease prevention"}' --filter '{"category":"health"}' --top-k 10
    pc index record search --index-name my-index --inputs '{"text":"disease prevention"}' --fields '["_id","chunk_text","category"]' --top-k 10
    pc index record search --index-name my-index --inputs '{"text":"disease prevention"}' --rerank '{"model":"bge-reranker-v2-m3","rank_fields":["chunk_text"]}' --top-k 10
    pc index record search --index-name my-index --inputs '{"text":"disease prevention"}' --match-terms '{"terms":["vaccine","prevention"]}' --top-k 10

    # Search by record ID for query vector (all index types)
    pc index record search --index-name my-index --id rec-123 --top-k 10

    # Vector search (all index types)
    pc index record search --index-name my-index --vector '[0.1,0.2,0.3]' --top-k 10
    pc index record search --index-name my-index --sparse-indices '[1,5,9]' --sparse-values '[0.4,0.8,0.2]' --top-k 10
    pc index record search --index-name my-index --vector '[0.1,0.2,0.3]' --sparse-indices '[1,5,9]' --sparse-values '[0.4,0.8,0.2]' --top-k 10

    # Full request body (must include top_k in the body)
    pc index record search --index-name my-index --body ./search.json
    ```

    ```text CLI theme={null}
    Usage: 5 (read units)
    ID          SCORE       FIELDS
    rec-001     0.912340    {"category":"health","chunk_text":"vaccine research..."}
    rec-002     0.887210    {"category":"health","chunk_text":"disease prevention..."}
    ```
  </Accordion>

  <Accordion title="pc index record upsert (Upsert records into an integrated index)">
    **Description**

    Upsert records into an integrated index namespace from a JSON or JSONL payload.

    The `--body` flag accepts a JSON object containing a `"records"` array of `IntegratedRecord` objects, a raw JSON array of records, or a JSONL stream of records (one object per line). The value can be inline JSON, a path to a `.json` or `.jsonl` file, or `-` to read from stdin.

    Records are sent in batches. The default batch size is 96 (the API maximum). Use `--batch-size` to send smaller batches.

    **Usage**

    ```bash theme={null}
    pc index record upsert [flags]
    ```

    **Flags**

    | Long flag      | Short flag | Description                                                                             |
    | :------------- | :--------- | :-------------------------------------------------------------------------------------- |
    | `--index-name` | `-i`       | Name of the index to upsert into (required)                                             |
    | `--body`       |            | Request body JSON or JSONL (inline JSON, `./path.json[l]`, or `-` for stdin) (required) |
    | `--namespace`  |            | Namespace to upsert into                                                                |
    | `--batch-size` | `-b`       | Number of records per batch (default: `96`, max: `96`)                                  |
    | `--json`       | `-j`       | Output in JSON format                                                                   |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Examples**

    ```bash theme={null}
    # Upsert from a JSON file
    pc index record upsert --index-name my-index --body ./records.json

    # Upsert from a JSONL file into a specific namespace
    pc index record upsert --index-name my-index --namespace my-namespace --body ./records.jsonl

    # Upsert from stdin
    cat records.jsonl | pc index record upsert --index-name my-index --namespace my-namespace --body -
    ```
  </Accordion>
</AccordionGroup>

### Collections

<AccordionGroup>
  <Accordion title="pc index collection create (Create a collection from a pod-based index)">
    **Description**

    Creates a static copy of a pod-based index as a collection. Collections can be used to store a snapshot of an index's data for backup or migration purposes.

    **Usage**

    ```bash theme={null}
    pc index collection create [flags]
    ```

    **Flags**

    | Long flag  | Short flag | Description                                                 |
    | :--------- | :--------- | :---------------------------------------------------------- |
    | `--name`   | `-n`       | Name to give the collection (required)                      |
    | `--source` | `-s`       | Name of the pod-based index to use as the source (required) |
    | `--json`   | `-j`       | Output in JSON format                                       |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Create a collection from a pod-based index
    pc index collection create --name my-collection --source my-index
    ```

    ```text CLI theme={null}
    ATTRIBUTE     VALUE
    Name          my-collection
    State         Initializing
    Dimension     1536
    Size          0
    VectorCount   0
    Environment   us-east-1-aws
    ```
  </Accordion>

  <Accordion title="pc index collection delete (Delete a collection)">
    **Description**

    Deletes a collection permanently. This action cannot be undone.

    **Usage**

    ```bash theme={null}
    pc index collection delete [flags]
    ```

    **Flags**

    | Long flag             | Short flag | Description                                                |
    | :-------------------- | :--------- | :--------------------------------------------------------- |
    | `--name`              | `-n`       | Name of the collection to delete (required)                |
    | `--skip-confirmation` |            | Skip the deletion confirmation prompt                      |
    | `--json`              | `-j`       | Output in JSON format (also skips the confirmation prompt) |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Delete a collection (prompts for confirmation)
    pc index collection delete --name my-collection

    # Skip the confirmation prompt
    pc index collection delete --name my-collection --skip-confirmation
    ```

    <Note>
      This command prompts for confirmation before deleting. Pass `--skip-confirmation` (or `--json`) to bypass the prompt in non-interactive contexts.
    </Note>
  </Accordion>

  <Accordion title="pc index collection describe (Describe a collection by name)">
    **Description**

    Returns detailed information about a single collection, including its state, dimension, size, vector count, and environment.

    **Usage**

    ```bash theme={null}
    pc index collection describe [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description                                   |
    | :-------- | :--------- | :-------------------------------------------- |
    | `--name`  | `-n`       | Name of the collection to describe (required) |
    | `--json`  | `-j`       | Output in JSON format                         |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Describe a collection
    pc index collection describe --name my-collection
    ```

    ```text CLI theme={null}
    ATTRIBUTE     VALUE
    Name          my-collection
    State         Ready
    Dimension     1536
    Size          104857600
    VectorCount   10000
    Environment   us-east-1-aws
    ```
  </Accordion>

  <Accordion title="pc index collection list (List collections in your project)">
    **Description**

    Lists all collections in your current project, sorted alphabetically by name.

    **Usage**

    ```bash theme={null}
    pc index collection list [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description           |
    | :-------- | :--------- | :-------------------- |
    | `--json`  | `-j`       | Output in JSON format |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # List all collections
    pc index collection list
    ```

    ```text CLI theme={null}
    NAME             DIMENSION   SIZE        STATUS   VECTORS   ENVIRONMENT
    my-collection    1536        104857600   Ready    10000     us-east-1-aws
    ```
  </Accordion>
</AccordionGroup>

### Backups

<AccordionGroup>
  <Accordion title="pc index backup create (Create a backup)">
    **Description**

    Creates a backup of a serverless index. Backups are static copies that only consume storage.

    **Usage**

    ```bash theme={null}
    pc index backup create [flags]
    ```

    **Flags**

    | Long flag       | Short flag | Description                                                          |
    | :-------------- | :--------- | :------------------------------------------------------------------- |
    | `--index-name`  | `-i`       | Name of the index to back up (required)                              |
    | `--name`        |            | Human-readable label for the backup (the backup ID is always a UUID) |
    | `--description` | `-d`       | Description for the backup                                           |
    | `--json`        | `-j`       | Output in JSON format                                                |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Create a backup
    pc index backup create -i my-index

    # Create with name and description
    pc index backup create -i my-index --name "nightly-backup" -d "Nightly backup before deployment"

    # JSON output
    pc index backup create -i my-index -j
    ```
  </Accordion>

  <Accordion title="pc index backup delete (Delete a backup)">
    **Description**

    Permanently deletes a backup. This operation cannot be undone.

    **Usage**

    ```bash theme={null}
    pc index backup delete [flags]
    ```

    **Flags**

    | Long flag             | Short flag | Description                                                |
    | :-------------------- | :--------- | :--------------------------------------------------------- |
    | `--id`                | `-i`       | Backup ID to delete (required)                             |
    | `--skip-confirmation` |            | Skip the deletion confirmation prompt                      |
    | `--json`              | `-j`       | Output in JSON format (also skips the confirmation prompt) |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Delete a backup by ID (prompts for confirmation)
    pc index backup delete -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f

    # Skip the confirmation prompt
    pc index backup delete -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f --skip-confirmation
    ```

    <Note>
      This command prompts for confirmation before deleting. Pass `--skip-confirmation` (or `--json`) to bypass the prompt in non-interactive contexts.
    </Note>

    <Warning>
      Backup deletion is permanent and cannot be undone.
    </Warning>
  </Accordion>

  <Accordion title="pc index backup describe (Show backup details)">
    **Description**

    Displays detailed information about a specific backup.

    **Usage**

    ```bash theme={null}
    pc index backup describe [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description                      |
    | :-------- | :--------- | :------------------------------- |
    | `--id`    | `-i`       | Backup ID to describe (required) |
    | `--json`  | `-j`       | Output in JSON format            |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Describe a backup
    pc index backup describe -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f

    # JSON output
    pc index backup describe -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f -j
    ```
  </Accordion>

  <Accordion title="pc index backup list (List backups)">
    **Description**

    Lists backups in the current project, optionally filtered by index name.

    **Usage**

    ```bash theme={null}
    pc index backup list [flags]
    ```

    **Flags**

    | Long flag            | Short flag | Description                    |
    | :------------------- | :--------- | :----------------------------- |
    | `--index-name`       | `-i`       | Filter backups by index name   |
    | `--limit`            | `-l`       | Maximum number of results      |
    | `--pagination-token` | `-p`       | Pagination token for next page |
    | `--json`             | `-j`       | Output in JSON format          |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # List all backups in the project
    pc index backup list

    # List backups for a specific index
    pc index backup list --index-name my-index

    # Limit results
    pc index backup list --limit 10

    # JSON output
    pc index backup list -j
    ```
  </Accordion>

  <Accordion title="pc index restore (Restore an index from a backup)">
    **Description**

    Creates a new index from a backup.

    **Usage**

    ```bash theme={null}
    pc index restore [flags]
    ```

    **Flags**

    | Long flag               | Short flag | Description                                          |
    | :---------------------- | :--------- | :--------------------------------------------------- |
    | `--id`                  | `-i`       | Backup ID (UUID) to restore from (required)          |
    | `--name`                | `-n`       | Name for the new index (required)                    |
    | `--deletion-protection` |            | Enable deletion protection - `enabled` or `disabled` |
    | `--tags`                | `-t`       | Tags to apply to the new index (key=value pairs)     |
    | `--json`                | `-j`       | Output in JSON format                                |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Restore an index from a backup
    pc index restore -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f -n restored-index

    # Restore with tags and deletion protection
    pc index restore -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f -n restored-index \
      --tags env=prod,team=search \
      --deletion-protection enabled

    # JSON output
    pc index restore -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f -n restored-index -j
    ```
  </Accordion>

  <Accordion title="pc index restore describe (Show restore job details)">
    **Description**

    Displays the status and details of a restore job.

    **Usage**

    ```bash theme={null}
    pc index restore describe [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description                           |
    | :-------- | :--------- | :------------------------------------ |
    | `--id`    | `-i`       | Restore job ID to describe (required) |
    | `--json`  | `-j`       | Output in JSON format                 |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Describe a restore job
    pc index restore describe -i rj-abc123

    # JSON output
    pc index restore describe -i rj-abc123 -j
    ```
  </Accordion>

  <Accordion title="pc index restore list (List restore jobs)">
    **Description**

    Lists all restore jobs in the current project.

    **Usage**

    ```bash theme={null}
    pc index restore list [flags]
    ```

    **Flags**

    | Long flag            | Short flag | Description                    |
    | :------------------- | :--------- | :----------------------------- |
    | `--limit`            | `-l`       | Maximum number of results      |
    | `--pagination-token` | `-p`       | Pagination token for next page |
    | `--json`             | `-j`       | Output in JSON format          |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # List restore jobs
    pc index restore list

    # Limit results
    pc index restore list --limit 10

    # JSON output
    pc index restore list -j
    ```
  </Accordion>
</AccordionGroup>

### Imports

<AccordionGroup>
  <Accordion title="pc index import start (Start an import from a storage URI)">
    **Description**

    Start an import that loads vector data from a storage provider into a serverless index. The URI must begin with the scheme of a supported provider (for example, `s3://`).

    For private buckets, configure a storage integration in the Pinecone console and pass the integration ID with `--integration-id`.

    Use `--error-mode` to control behavior when records fail: `continue` skips failing records and keeps going; `abort` stops the import on first error. Defaults to `continue`.

    **Usage**

    ```bash theme={null}
    pc index import start [flags]
    ```

    **Flags**

    | Long flag          | Short flag | Description                                                           |
    | :----------------- | :--------- | :-------------------------------------------------------------------- |
    | `--index-name`     | `-i`       | Name of the index to import into (required)                           |
    | `--uri`            | `-u`       | URI of the data to import, for example `s3://bucket/path/` (required) |
    | `--integration-id` |            | Storage integration ID for private buckets                            |
    | `--error-mode`     |            | How to handle record errors: `continue` (default) or `abort`          |
    | `--json`           | `-j`       | Output in JSON format                                                 |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Examples**

    ```bash theme={null}
    # Start an import from a public S3 bucket
    pc index import start --index-name my-index --uri s3://my-bucket/data/

    # Start an import from a private bucket using a storage integration
    pc index import start --index-name my-index --uri s3://my-bucket/data/ --integration-id intg-123

    # Abort on the first error instead of continuing
    pc index import start --index-name my-index --uri s3://my-bucket/data/ --error-mode abort

    # JSON output
    pc index import start --index-name my-index --uri s3://my-bucket/data/ -j
    ```

    ```text CLI theme={null}
    Import imp-abc123 started.
    ATTRIBUTE    VALUE
    Import ID    imp-abc123
    ```
  </Accordion>

  <Accordion title="pc index import describe (Describe an import operation)">
    **Description**

    Show the current status and details of an import operation, including
    percent complete, records imported, and any error messages.

    **Usage**

    ```bash theme={null}
    pc index import describe [flags]
    ```

    **Flags**

    | Long flag      | Short flag | Description                                        |
    | :------------- | :--------- | :------------------------------------------------- |
    | `--index-name` | `-i`       | Name of the index the import belongs to (required) |
    | `--id`         |            | ID of the import to describe (required)            |
    | `--json`       | `-j`       | Output in JSON format                              |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Describe an import operation
    pc index import describe --index-name my-index --id import-123

    # JSON output
    pc index import describe --index-name my-index --id import-123 -j
    ```

    ```text CLI theme={null}
    ATTRIBUTE         VALUE
    Import ID         import-123
    Status            InProgress
    URI               s3://my-bucket/data/
    Percent Complete  45.0%
    Records Imported  450
    Created At        2024-01-15 12:00:00
    Finished At       -
    Error             None
    ```
  </Accordion>

  <Accordion title="pc index import list (List import operations for an index)">
    **Description**

    List bulk import operations for the given index, with optional pagination.

    **Usage**

    ```bash theme={null}
    pc index import list [flags]
    ```

    **Flags**

    | Long flag            | Short flag | Description                                               |
    | :------------------- | :--------- | :-------------------------------------------------------- |
    | `--index-name`       | `-i`       | Name of the index to list imports for (required)          |
    | `--limit`            | `-l`       | Maximum number of imports to return                       |
    | `--pagination-token` | `-p`       | Pagination token to continue a previous listing operation |
    | `--json`             | `-j`       | Output in JSON format                                     |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Examples**

    ```bash theme={null}
    # List all imports for an index
    pc index import list --index-name my-index

    # List imports with a page size limit
    pc index import list --index-name my-index --limit 10

    # Continue paginating from a previous call
    pc index import list --index-name my-index --pagination-token eyJ...

    # JSON output
    pc index import list --index-name my-index -j
    ```

    ```text CLI theme={null}
    IMPORT ID     STATUS      URI                     PERCENT  RECORDS  CREATED              FINISHED
    imp-abc123    Completed   s3://my-bucket/data/    100.0%   1000     2024-01-15 12:00:00  2024-01-15 12:05:00
    imp-def456    InProgress  s3://other-bucket/data/ 45.0%    450      2024-01-15 13:00:00  -
    ```
  </Accordion>

  <Accordion title="pc index import cancel (Cancel an in-progress import operation)">
    **Description**

    Cancel an import operation that is currently pending or in progress.
    Already-completed or failed imports cannot be canceled.

    **Usage**

    ```bash theme={null}
    pc index import cancel [flags]
    ```

    **Flags**

    | Long flag      | Short flag | Description                                        |
    | :------------- | :--------- | :------------------------------------------------- |
    | `--index-name` | `-i`       | Name of the index the import belongs to (required) |
    | `--id`         |            | ID of the import to cancel (required)              |
    | `--json`       | `-j`       | Output in JSON format                              |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Cancel an import operation
    pc index import cancel --index-name my-index --id import-123

    # JSON output
    pc index import cancel --index-name my-index --id import-123 -j
    ```

    ```text CLI theme={null}
    Import import-123 canceled.
    ```
  </Accordion>
</AccordionGroup>

### Projects

<AccordionGroup>
  <Accordion title="pc project create (Create a new project)">
    **Description**

    Creates a new project in your [target organization](/reference/cli/target-context), using the specified configuration.

    **Usage**

    ```bash theme={null}
    pc project create [flags]
    ```

    **Flags**

    | Long flag            | Short flag | Description                                                    |
    | :------------------- | :--------- | :------------------------------------------------------------- |
    | `--force-encryption` |            | Enable encryption with CMEK                                    |
    | `--json`             | `-j`       | Output in JSON format                                          |
    | `--name`             | `-n`       | Project name (required)                                        |
    | `--target`           |            | Automatically target the project in the CLI after it's created |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Basic project creation
    pc project create -n "demo-project"
    ```
  </Accordion>

  <Accordion title="pc project delete (Delete a project)">
    **Description**

    Permanently deletes a project and all its resources. This operation cannot be undone.

    **Usage**

    ```bash theme={null}
    pc project delete [flags]
    ```

    **Flags**

    | Long flag             | Short flag | Description                                                 |
    | :-------------------- | :--------- | :---------------------------------------------------------- |
    | `--id`                | `-i`       | Project ID (optional, uses target project if not specified) |
    | `--json`              | `-j`       | Output in JSON format                                       |
    | `--skip-confirmation` |            | Skip confirmation prompt                                    |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Delete target project
    pc project delete

    # Delete specific project
    pc project delete -i proj-abc123

    # Skip confirmation
    pc project delete -i proj-abc123 --skip-confirmation
    ```

    <Note>
      Must delete all indexes and collections in the project first. If the deleted project is your current target, set a new target after deleting it.
    </Note>
  </Accordion>

  <Accordion title="pc project describe (Show project details)">
    **Description**

    Displays detailed information about a specific project, including various details.

    **Usage**

    ```bash theme={null}
    pc project describe [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description           |
    | :-------- | :--------- | :-------------------- |
    | `--id`    | `-i`       | Project ID (required) |
    | `--json`  | `-j`       | Output in JSON format |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Describe a project
    pc project describe -i proj-abc123

    # JSON output
    pc project describe -i proj-abc123 --json

    # Find ID and describe
    pc project list
    pc project describe -i proj-abc123
    ```
  </Accordion>

  <Accordion title="pc project list (List all projects)">
    **Description**

    Displays all projects in your [target organization](/reference/cli/target-context), including various details.

    **Usage**

    ```bash theme={null}
    pc project list [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description           |
    | :-------- | :--------- | :-------------------- |
    | `--json`  | `-j`       | Output in JSON format |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # List all projects
    pc project list

    # JSON output
    pc project list --json

    # List after login
    pc auth login
    pc auth target -o "my-org"
    pc project list
    ```
  </Accordion>

  <Accordion title="pc project update (Update project settings)">
    **Description**

    Modifies the configuration of the [target project](/reference/cli/target-context), or a specific project ID.

    **Usage**

    ```bash theme={null}
    pc project update [flags]
    ```

    **Flags**

    | Long flag            | Short flag | Description                         |
    | :------------------- | :--------- | :---------------------------------- |
    | `--force-encryption` | `-f`       | Enable/disable encryption with CMEK |
    | `--id`               | `-i`       | Project ID (required)               |
    | `--json`             | `-j`       | Output in JSON format               |
    | `--name`             | `-n`       | New project name                    |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Update name
    pc project update -i proj-abc123 -n "new-name"
    ```
  </Accordion>
</AccordionGroup>

### Organizations

<AccordionGroup>
  <Accordion title="pc organization delete (Delete an organization)">
    **Description**

    Permanently deletes an organization and all its resources. This operation cannot be undone.

    **Usage**

    ```bash theme={null}
    pc organization delete [flags]
    ```

    **Flags**

    | Long flag             | Short flag | Description                |
    | :-------------------- | :--------- | :------------------------- |
    | `--id`                | `-i`       | Organization ID (required) |
    | `--json`              | `-j`       | Output in JSON format      |
    | `--skip-confirmation` |            | Skip confirmation prompt   |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Delete an organization
    pc organization delete -i org-abc123

    # Skip confirmation
    pc organization delete -i org-abc123 --skip-confirmation
    ```

    <Note>
      This is a highly destructive action. Deletion is permanent. If the deleted organization is your current [target](/reference/cli/target-context), set a new target after deleting.
    </Note>
  </Accordion>

  <Accordion title="pc organization describe (Show organization details)">
    **Description**

    Displays detailed information about a specific organization, including name, ID, creation date, payment status, plan, and support tier.

    **Usage**

    ```bash theme={null}
    pc organization describe [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description                |
    | :-------- | :--------- | :------------------------- |
    | `--id`    | `-i`       | Organization ID (required) |
    | `--json`  | `-j`       | Output in JSON format      |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Describe an organization
    pc organization describe -i org-abc123

    # JSON output
    pc organization describe -i org-abc123 --json

    # Find ID and describe
    pc organization list
    pc organization describe -i org-abc123
    ```
  </Accordion>

  <Accordion title="pc organization list (List organizations)">
    **Description**

    Displays all organizations that the authenticated user has access to, including name, ID, creation date, payment status, plan, and support tier.

    **Usage**

    ```bash theme={null}
    pc organization list [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description           |
    | :-------- | :--------- | :-------------------- |
    | `--json`  | `-j`       | Output in JSON format |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # List all organizations
    pc organization list

    # JSON output
    pc organization list --json

    # List after login
    pc auth login
    pc organization list
    ```
  </Accordion>

  <Accordion title="pc organization update (Update organization settings)">
    **Description**

    Modifies the configuration of the [target organization](/reference/cli/target-context), or a specific organization ID.

    **Usage**

    ```bash theme={null}
    pc organization update [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description                |
    | :-------- | :--------- | :------------------------- |
    | `--id`    | `-i`       | Organization ID (required) |
    | `--json`  | `-j`       | Output in JSON format      |
    | `--name`  | `-n`       | New organization name      |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Update name
    pc organization update -i org-abc123 -n "new-name"

    # Verify changes
    pc organization update -i org-abc123 -n "Acme Corp"
    pc organization describe -i org-abc123
    ```
  </Accordion>
</AccordionGroup>

### API keys

<AccordionGroup>
  <Accordion title="pc api-key create (Create a new API key)">
    **Description**

    Creates a new API key for the current [target project](/reference/cli/target-context) or a specific project ID. Optionally stores the key locally for CLI use.

    **Usage**

    ```bash theme={null}
    pc api-key create [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description                                                                             |
    | :-------- | :--------- | :-------------------------------------------------------------------------------------- |
    | `--id`    | `-i`       | Project ID (optional, uses target project if not specified)                             |
    | `--json`  | `-j`       | Output in JSON format                                                                   |
    | `--name`  | `-n`       | Key name (required)                                                                     |
    | `--roles` |            | Roles to assign (default: `ProjectEditor`)                                              |
    | `--store` |            | Store the key locally for CLI use (automatically replaces any existing CLI-managed key) |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Basic key creation
    pc api-key create -n "my-key"

    # Create and store locally
    pc api-key create -n "my-key" --store

    # Create with specific role
    pc api-key create -n "my-key" --store --roles ProjectEditor

    # Create for specific project
    pc api-key create -n "my-key" -i proj-abc123
    ```

    <Note>
      API keys are scoped to a specific organization and project.
    </Note>
  </Accordion>

  <Accordion title="pc api-key delete (Delete an API key)">
    **Description**

    Permanently deletes an API key. Applications using this key immediately lose access.

    **Usage**

    ```bash theme={null}
    pc api-key delete [flags]
    ```

    **Flags**

    | Long flag             | Short flag | Description              |
    | :-------------------- | :--------- | :----------------------- |
    | `--id`                | `-i`       | API key ID (required)    |
    | `--skip-confirmation` |            | Skip confirmation prompt |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Delete an API key
    pc api-key delete -i key-abc123

    # Skip confirmation
    pc api-key delete -i key-abc123 --skip-confirmation

    # Delete and clean up local storage
    pc api-key delete -i key-abc123
    pc auth local-keys prune --skip-confirmation
    ```

    <Note>
      Deletion is permanent. Applications using this key immediately lose access to Pinecone.
    </Note>
  </Accordion>

  <Accordion title="pc api-key describe (Show API key details)">
    **Description**

    Displays detailed information about a specific API key, including its name, ID, project ID, and roles.

    **Usage**

    ```bash theme={null}
    pc api-key describe [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description           |
    | :-------- | :--------- | :-------------------- |
    | `--id`    | `-i`       | API key ID (required) |
    | `--json`  | `-j`       | Output in JSON format |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Describe an API key
    pc api-key describe -i key-abc123

    # JSON output
    pc api-key describe -i key-abc123 --json

    # Find ID and describe
    pc api-key list
    pc api-key describe -i key-abc123
    ```

    <Note>
      Does not display the actual key value.
    </Note>
  </Accordion>

  <Accordion title="pc api-key list (List all API keys)">
    **Description**

    Displays a list of all of the [target project's](/reference/cli/target-context) API keys, as found in  Pinecone (regardless of whether they are stored locally by the CLI). Displays various details about each key, including name, ID, project ID, and roles.

    **Usage**

    ```bash theme={null}
    pc api-key list [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description                                                 |
    | :-------- | :--------- | :---------------------------------------------------------- |
    | `--id`    | `-i`       | Project ID (optional, uses target project if not specified) |
    | `--json`  | `-j`       | Output in JSON format                                       |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # List keys for target project
    pc api-key list

    # List for specific project
    pc api-key list -i proj-abc123

    # JSON output
    pc api-key list --json
    ```

    <Note>
      Does not display key values.
    </Note>
  </Accordion>

  <Accordion title="pc api-key update (Update API key settings)">
    **Description**

    Updates the name and roles of an API key.

    **Usage**

    ```bash theme={null}
    pc api-key update [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description           |
    | :-------- | :--------- | :-------------------- |
    | `--id`    | `-i`       | API key ID (required) |
    | `--json`  | `-j`       | Output in JSON format |
    | `--name`  | `-n`       | New key name          |
    | `--roles` | `-r`       | Roles to assign       |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    # Update name
    pc api-key update -i key-abc123 -n "new-name"

    # Update roles
    pc api-key update -i key-abc123 -r ProjectEditor

    # Verify changes
    pc api-key update -i key-abc123 -n "production-key"
    pc api-key describe -i key-abc123
    ```

    <Note>
      Cannot change the actual key. If you need a different key, create a new one.
    </Note>
  </Accordion>
</AccordionGroup>

### Config

<AccordionGroup>
  <Accordion title="pc config list (List all configuration settings and their current values)">
    **Description**

    Lists all CLI configuration settings and their current values. Sensitive values like `api-key` are masked by default; use `--reveal` to see the full value. Hidden settings such as `environment` are included when `--all` is passed.

    **Usage**

    ```bash theme={null}
    pc config list [flags]
    ```

    **Flags**

    | Long flag  | Short flag | Description                                               |
    | :--------- | :--------- | :-------------------------------------------------------- |
    | `--reveal` |            | Reveal the full value for sensitive settings like api-key |
    | `--json`   | `-j`       | Output in JSON format                                     |
    | `--all`    |            | Include hidden settings such as environment               |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    pc config list
    pc config list --all
    pc config list --reveal
    pc config list --json
    ```

    ```text CLI theme={null}
    KEY         VALUE             ENV VAR NAME        ENV VAR OVERRIDE  DESCRIPTION
    api-key     ****abcd****      PINECONE_API_KEY     false             Default API key for authenticating with Pinecone
    color       true                                                     Enable colored output
    ```
  </Accordion>

  <Accordion title="pc config get <key> (Get the current value of a configuration setting)">
    **Description**

    Gets the current value of a configuration setting. Valid keys are: `api-key`, `color`, `environment`. Sensitive values like `api-key` are masked by default; use `--reveal` to see the full value.

    **Usage**

    ```bash theme={null}
    pc config get <key> [flags]
    ```

    **Flags**

    | Long flag  | Short flag | Description                                               |
    | :--------- | :--------- | :-------------------------------------------------------- |
    | `--reveal` |            | Reveal the full value for sensitive settings like api-key |
    | `--json`   | `-j`       | Output in JSON format                                     |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    pc config get api-key
    pc config get api-key --reveal
    pc config get environment
    pc config get color
    ```
  </Accordion>

  <Accordion title="pc config describe <key> (Show detailed information about a configuration setting)">
    **Description**

    Displays detailed information about a specific CLI configuration setting, including its current value, whether an environment variable is overriding it, and valid values. Valid keys are: `api-key`, `color`, `environment`.

    **Usage**

    ```bash theme={null}
    pc config describe <key> [flags]
    ```

    **Flags**

    | Long flag  | Short flag | Description                                               |
    | :--------- | :--------- | :-------------------------------------------------------- |
    | `--reveal` |            | Reveal the full value for sensitive settings like api-key |
    | `--json`   | `-j`       | Output in JSON format                                     |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    pc config describe api-key
    pc config describe color
    pc config describe color --json
    ```

    ```text CLI theme={null}
    KEY               api-key
    VALUE             ****abcd****
    ENV VAR NAME      $PINECONE_API_KEY
    ENV VAR OVERRIDE  false
    SENSITIVE         true
    DESCRIPTION       Default API key for authenticating with Pinecone
    ```
  </Accordion>

  <Accordion title="pc config set <key> <value> (Set a configuration value)">
    **Description**

    Sets a CLI configuration value. Valid keys are: `api-key`, `color`, `environment`. The value is persisted to the local config file.

    **Usage**

    ```bash theme={null}
    pc config set <key> <value> [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description           |
    | :-------- | :--------- | :-------------------- |
    | `--json`  | `-j`       | Output in JSON format |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    pc config set api-key pcsk_...
    pc config set environment staging
    pc config set color false
    ```
  </Accordion>

  <Accordion title="pc config unset <key> (Reset a configuration value to its default)">
    **Description**

    Resets a CLI configuration value to its default. Valid keys are: `api-key`, `color`, `environment`.

    **Usage**

    ```bash theme={null}
    pc config unset <key> [flags]
    ```

    **Flags**

    | Long flag | Short flag | Description           |
    | :-------- | :--------- | :-------------------- |
    | `--json`  | `-j`       | Output in JSON format |

    **Global Flags**

    | Long flag   | Short flag | Description                         |
    | :---------- | :--------- | :---------------------------------- |
    | `--help`    | `-h`       | Show help information               |
    | `--quiet`   | `-q`       | Suppress output                     |
    | `--timeout` |            | Timeout (default 60s, 0 to disable) |

    **Example**

    ```bash theme={null}
    pc config unset api-key
    pc config unset color
    ```
  </Accordion>
</AccordionGroup>


# CLI quickstart
Source: https://docs.pinecone.io/reference/cli/quickstart

Pinecone CLI quickstart for installing pc, authenticating, and managing indexes, vectors, and data imports directly from your terminal.

The Pinecone CLI (`pc`) lets you manage Pinecone resources directly from your terminal.

## Install

<Tabs>
  <Tab title="macOS (Homebrew)">
    ```bash theme={null}
    brew tap pinecone-io/tap
    brew install pinecone-io/tap/pinecone
    ```
  </Tab>

  <Tab title="Other platforms">
    Pre-built binaries for macOS, Linux, and Windows are available on the [GitHub Releases page](https://github.com/pinecone-io/cli/releases).

    | Platform | Architectures                          |
    | :------- | :------------------------------------- |
    | macOS    | Intel (x86\_64), Apple Silicon (ARM64) |
    | Linux    | x86\_64, ARM64, i386                   |
    | Windows  | x86\_64, i386                          |
  </Tab>
</Tabs>

## Authenticate

```bash theme={null}
pc auth login
```

Visit the URL in your terminal to sign in. The CLI automatically sets your default organization and project.

To target a different org/project:

```bash theme={null}
pc target -o "my-org" -p "my-project"
```

<Tip>
  For CI/CD or automation, you can also authenticate with a [service account](/reference/cli/authentication#service-account) or [API key](/reference/cli/authentication#api-key).
</Tip>

## Manage indexes

```bash theme={null}
# List indexes
pc index list

# Create an index
pc index create -n my-index -d 3 -m cosine -c aws -r us-east-1

# Get index details
pc index describe -i my-index

# Get index statistics
pc index stats -i my-index
```

## Work with vectors

```bash theme={null}
# Upsert vectors (from file or inline JSON)
pc index vector upsert -i my-index \
  --body '{"vectors": [{"id": "vec1", "values": [0.1, 0.2, 0.3], "metadata": {"genre": "comedy"}}]}'

# Import from a large dataset in object storage (S3, GCS, Azure)
pc index import start -i my-index --uri s3://my-bucket/data/

# Check the progress of an import operation
pc index import list --i my-index
pc index import describe --i my-index --id import-123

# Query (vector can be inline or in a file)
pc index vector query -i my-index \
  --vector '[0.1, 0.2, 0.3]' \
  --top-k 10 \
  --include-metadata

# Fetch by ID (from file or inline JSON)
pc index vector fetch -i my-index --ids '["vec1","vec2"]'

# List vector IDs from an index
pc index vector list -i my-index
```

## Manage namespaces

```bash theme={null}
# List namespaces
pc index namespace list -i my-index

# Create a namespace
pc index namespace create -i my-index --name tenant-a

# Delete a namespace
pc index namespace delete -i my-index --name tenant-a
```

## Back up and restore

```bash theme={null}
# Create a backup
pc index backup create -i my-index --name "my-index-backup"

# List backups (show index, backup name, backup ID, etc.)
pc index backup list -i my-index

# Restore from backup (by ID, not name)
pc index restore -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f -n restored-index
```

## JSON output

Add `-j` to any command for JSON output:

```bash theme={null}
pc index list -j
pc index describe -i my-index -j
```

## Getting help

Use `-h` or `--help` with any command to see available options:

```bash theme={null}
pc -h
pc index -h
pc index create -h
```

## Next steps

* [Command reference](/reference/cli/command-reference) — Full list of commands and flags
* [Authentication](/reference/cli/authentication) — Service accounts, API keys, and auth priority
* [Target context](/reference/cli/target-context) — How org/project targeting works


# CLI target context
Source: https://docs.pinecone.io/reference/cli/target-context

Pinecone CLI: The CLI's **target context** determines which organization and project your commands operate on. You must authenticate before setting target.

The CLI's **target context** determines which organization and project your commands operate on. You must [authenticate](/reference/cli/authentication) before setting target context.

## Flags

| Flag                | Short | Default | Description                                                                       |
| ------------------- | ----- | ------- | --------------------------------------------------------------------------------- |
| `--org`             | `-o`  | —       | Target organization by name. Mutually exclusive with `--organization-id`.         |
| `--organization-id` | —     | —       | Target organization by ID. Mutually exclusive with `--org`.                       |
| `--project`         | `-p`  | —       | Target project by name. Mutually exclusive with `--project-id`.                   |
| `--project-id`      | —     | —       | Target project by ID. Mutually exclusive with `--project`.                        |
| `--show`            | `-s`  | `false` | Show the current target context.                                                  |
| `--clear`           | —     | `false` | Clear the stored target context.                                                  |
| `--json`            | `-j`  | `false` | Output as JSON. In non-TTY environments (CI/CD, pipes), JSON output is automatic. |

<Note>
  `--org` and `--organization-id` are mutually exclusive — use one or the other. The same applies to `--project` and `--project-id`.
</Note>

## How operations use target context

| Operation type                   | Scope                                    |
| -------------------------------- | ---------------------------------------- |
| Control plane (indexes, backups) | Target project                           |
| Data plane (vectors, namespaces) | Target project + specified index         |
| Admin API (organizations)        | No target context needed                 |
| Admin API (projects)             | Target organization                      |
| Admin API (API keys)             | Target project (unless `--id` specified) |

## Target context by auth method

### User login

After `pc auth login`, the CLI auto-targets your default organization and its first project.

```bash theme={null}
# Change target
pc target -o "my-org" -p "my-project"
```

### Service account

**Via CLI command:** After `pc auth configure --client-id --client-secret`, the CLI auto-targets the service account's organization. For the project:

* If one project exists, it's auto-targeted
* If multiple exist, you're prompted (or use `--project-id`)
* If none exist, create one and target it manually

**Via environment variables:** If using `PINECONE_CLIENT_ID` and `PINECONE_CLIENT_SECRET` without running `pc auth configure`, no target context is set automatically. Run `pc target` to set it.

```bash theme={null}
# Change project (org is fixed to the service account's org)
pc target -p "my-project"

# Or select interactively
pc target
```

### API key

<Warning>
  When using an API key, control plane and data plane operations use the **key's org/project scope**, not the CLI's stored target context. The `pc target --show` output does not reflect what these operations actually use.
</Warning>

API keys are scoped to a specific org and project and cannot access resources outside that scope.

Admin API operations still use your user login or service account credentials (API keys can't authenticate Admin API calls).

## Managing target context

```bash theme={null}
pc target --show   # View current target
pc target --clear  # Clear target context
```

### JSON mode and non-TTY environments

Running `pc target --json` with no targeting flags returns the current target context as a JSON object. This is a local-state read — **no authentication is required**:

```bash theme={null}
pc target --json
```

In non-TTY environments (CI/CD pipelines, shell pipes, scripts), JSON output is automatic — the same as passing `--json` explicitly. You do not need to add the flag in automation contexts.

Use `--organization-id` and `--project-id` (instead of name flags) to set context reliably in scripts, since IDs are stable and unaffected by renames:

```bash theme={null}
pc target --organization-id "org-abc123" --project-id "proj-xyz789" --json
```


# Pinecone SDKs overview
Source: https://docs.pinecone.io/reference/pinecone-sdks

Browse official Pinecone SDKs for Python, Node.js, Java, and Go, including the version mappings between SDK releases and API versions.

## Pinecone SDKs

Official Pinecone SDKs provide convenient access to the [Pinecone APIs](/reference/api/introduction).

<CardGroup>
  <Card title="Python SDK" icon="python" href="/reference/sdks/python/overview" />

  <Card title="Node.js SDK" icon="node-js" href="/reference/sdks/node/overview" />

  <Card title="Java SDK" icon="java" href="/reference/sdks/java/overview" />

  <Card title="Go SDK" icon="golang" href="/reference/sdks/go/overview" />
</CardGroup>

## SDK versions

SDK versions are pinned to specific [API versions](/reference/api/versioning). When a new API version is released, a new version of the SDK is also released.

The mappings between API versions and SDK versions are as follows:

|                                               | `2026-04`   | `2025-10` | `2025-04` | `2025-01` | `2024-10` | `2024-07`     | `2024-04` |
| --------------------------------------------- | :---------- | :-------- | :-------- | :-------- | :-------- | :------------ | :-------- |
| [Python SDK](/reference/sdks/python/overview) | v9.x        | v8.x      | v7.x      | v6.x      | v5.3.x    | v5.0.x-v5.2.x | v4.x      |
| [Node.js SDK](/reference/sdks/node/overview)  | v8.x        | v7.x      | v6.x      | v5.x      | v4.x      | v3.x          | v2.x      |
| [Java SDK](/reference/sdks/java/overview)     | Coming soon | v6.x      | v5.x      | v4.x      | v3.x      | v2.x          | v1.x      |
| [Go SDK](/reference/sdks/go/overview)         | v6.x        | v5.x      | v4.x      | v3.x      | v2.x      | v1.x          | v0.x      |

When a new stable API version is released, you should upgrade your SDK to the latest version to ensure compatibility with the latest API changes.

<Note>
  The Java SDK targeting API version `2026-04` will be available soon.
</Note>

## Limitations

While Pinecone tracks read unit usage with decimal precision, the Pinecone API and SDKs round these values up to the nearest whole number in query, fetch, and list responses. For example, if a query uses 0.45 read units, the API and SDKs will report it as 1 read unit.

For precise read unit reporting, see [index-level metrics](/guides/production/monitoring) or the organization-wide [Usage dashboard](/guides/manage-cost/monitor-usage-and-costs#monitor-organization-level-usage-and-costs).

## Community SDKs

Find community-contributed SDKs for Pinecone. These libraries are not supported by Pinecone.

* [Ruby SDK](https://github.com/ScotterC/pinecone) (contributed by [ScotterC](https://github.com/ScotterC))

* [Scala SDK](https://github.com/cequence-io/pinecone-scala) (contributed by [cequence-io](https://github.com/cequence-io))

* [PHP SDK](https://github.com/probots-io/pinecone-php) (contributed by [protobots-io](https://github.com/probots-io))


# Pinecone Go SDK
Source: https://docs.pinecone.io/reference/sdks/go/overview

Install and use the Pinecone Go SDK to manage indexes and namespaces, upsert vectors, run semantic search, and call the Admin and Inference APIs from Go.

<Tip>
  For installation instructions and usage examples, see the [Go SDK documentation](https://github.com/pinecone-io/go-pinecone). To report an issue or request a feature, [file an issue on GitHub](https://github.com/pinecone-io/go-pinecone/issues).
</Tip>

## Requirements

The Pinecone Go SDK requires a Go version with [modules](https://go.dev/wiki/Modules) support.

## SDK versions

SDK versions are pinned to specific [API versions](/reference/api/versioning). When a new API version is released, a new version of the SDK is also released.

The mappings between API versions and Go SDK versions are as follows:

| API version | SDK version |
| :---------- | :---------- |
| `2026-04`   | v6.x        |
| `2025-10`   | v5.x        |
| `2025-04`   | v4.x        |
| `2025-01`   | v3.x        |
| `2024-10`   | v2.x        |
| `2024-07`   | v1.x        |
| `2024-04`   | v0.x        |

When a new stable API version is released, you should upgrade your SDK to the latest version to ensure compatibility with the latest API changes.

## Install

To install the latest version of the [Go SDK](https://github.com/pinecone-io/go-pinecone), add a dependency to the current module:

```shell theme={null}
go get github.com/pinecone-io/go-pinecone/v6/pinecone
```

To install a specific version of the Go SDK, run the following command:

```shell theme={null}
go get github.com/pinecone-io/go-pinecone/v6/pinecone@<version>
```

To check your SDK version, run the following command:

```shell theme={null}
go list -u -m all | grep go-pinecone
```

## Upgrade

<Warning>
  Before upgrading to `v3.0.0` or later, update all relevant code to account for the breaking changes explained [here](/release-notes/2025#2025-02-07-4).
</Warning>

Each major version carries its version number in the module path, so crossing a major requires updating the import path in every file that uses the SDK. For example, moving from `v4` to `v6` means changing:

```go theme={null}
// before
import "github.com/pinecone-io/go-pinecone/v4/pinecone"

// after
import "github.com/pinecone-io/go-pinecone/v6/pinecone"
```

Apart from the module path, `v5.0.0` and `v6.0.0` are backward compatible with the release lines before them.

If you already have the Go SDK, upgrade to the latest version as follows:

```shell theme={null}
go get -u github.com/pinecone-io/go-pinecone/v6/pinecone@latest
```

## Initialize

Once installed, you can import the SDK and then use an [API key](/guides/production/security-overview#api-keys) to initialize a client instance:

```Go theme={null}
package main

import (
    "context"
    "log"

    "github.com/pinecone-io/go-pinecone/v6/pinecone"
)

func main() {
    ctx := context.Background()

    pc, err := pinecone.NewClient(pinecone.NewClientParams{
        ApiKey: "YOUR_API_KEY",
    })
    if err != nil {
        log.Fatalf("Failed to create Client: %v", err)
    }
} 
```

To manage organizations, projects, API keys, and [role-based access control](/guides/production/manage-rbac), initialize an `AdminClient` with [service account](/guides/organizations/manage-service-accounts) credentials instead:

```Go theme={null}
package main

import (
    "context"
    "log"
    "os"

    "github.com/pinecone-io/go-pinecone/v6/pinecone"
)

func main() {
    ctx := context.Background()

    adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
        ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
        ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
    })
    if err != nil {
        log.Fatalf("Failed to create AdminClient: %v", err)
    }
}
```


# Reference
Source: https://docs.pinecone.io/reference/sdks/go/reference

Reference documentation for the Pinecone Go SDK, including client setup, types, and methods for managing indexes and vector data operations.



# OpenTelemetry support
Source: https://docs.pinecone.io/reference/sdks/java/open-telemetry

Monitor Pinecone Java SDK operations with OpenTelemetry metrics for client latency, server processing time, and errors via Prometheus.

The Pinecone Java SDK provides built-in support for capturing per-operation response metadata, making it straightforward to monitor your Pinecone usage with [OpenTelemetry](https://opentelemetry.io/) or any other observability system.

With this feature, you can track client-side latency, server processing time, network overhead, error rates, and more for every data plane operation your application makes.

## How it all fits together

The SDK's observability support is designed to be flexible. You don't need to adopt the entire observability stack at once -- start simple and add layers as your needs grow.

Here are the components involved and how they relate to each other:

* **Pinecone Java SDK**: Exposes a `ResponseMetadataListener` callback, a plain Java interface with no external dependencies. At its simplest, you can log the metadata to the console. No additional tools required.
* **[OpenTelemetry](https://opentelemetry.io/) (OTel)**: An open standard and SDK for producing structured telemetry data (metrics, traces, logs). If you want standardized metrics that follow [semantic conventions](https://opentelemetry.io/docs/specs/semconv/database/database-spans/), you add the OTel SDK and wire it to the listener. This is optional.
* **OTel Collector**: A vendor-neutral service that receives telemetry from your app and forwards it to a storage backend. Optional -- many setups export directly from the app to a backend.
* **Prometheus**: A time-series database that stores metrics, making them queryable over time. One popular storage option.
* **Grafana**: A visualization and dashboarding tool that queries Prometheus (or other backends) and displays charts and alerts. One popular visualization option.

A common setup chains these together:

```
Your App (OTel SDK) → OTel Collector → Prometheus (storage) → Grafana (visualization)
```

<Note>
  This is just one example pipeline. You can substitute Datadog, New Relic, or any OTel-compatible backend. You can also skip OTel entirely and use [Micrometer](#example-micrometerprometheus), custom logging, or any approach that suits your stack.
</Note>

## Response metadata listener

The Java SDK captures response metadata through a `ResponseMetadataListener` -- a functional interface you provide when building the Pinecone client. The listener is called after each data plane operation completes (whether it succeeds or fails), and receives a `ResponseMetadata` object containing timing, status, and context information.

The SDK itself has no OpenTelemetry dependency. You bring your own observability library and decide what to do with the metadata.

### Supported operations

The following data plane operations are instrumented, for both synchronous (`Index`) and asynchronous (`AsyncIndex`) usage:

| Operation | Description                |
| --------- | -------------------------- |
| `upsert`  | Insert or update vectors   |
| `query`   | Search for similar vectors |
| `fetch`   | Retrieve vectors by ID     |
| `update`  | Update vector metadata     |
| `delete`  | Delete vectors             |

### Available metadata

Each `ResponseMetadata` object provides the following fields:

| Method                   | Description                                        | OTel attribute            |
| ------------------------ | -------------------------------------------------- | ------------------------- |
| `getOperationName()`     | Operation type (e.g., `upsert`, `query`)           | `db.operation.name`       |
| `getIndexName()`         | Pinecone index name                                | `pinecone.index_name`     |
| `getNamespace()`         | Namespace (empty string if default)                | `db.namespace`            |
| `getServerAddress()`     | Pinecone server host                               | `server.address`          |
| `getClientDurationMs()`  | Total round-trip time in ms (always available)     | --                        |
| `getServerDurationMs()`  | Server processing time in ms (may be `null`)       | --                        |
| `getNetworkOverheadMs()` | Client minus server duration in ms (may be `null`) | --                        |
| `getStatus()`            | `"success"` or `"error"`                           | `status`                  |
| `getGrpcStatusCode()`    | Raw gRPC status code (e.g., `OK`, `UNAVAILABLE`)   | `db.response.status_code` |
| `getErrorType()`         | Error category, or `null` if successful            | `error.type`              |

Possible `errorType` values: `validation`, `connection`, `server`, `rate_limit`, `timeout`, `auth`, `not_found`, `unknown`.

### Recommended metrics

If you're recording OTel metrics, the SDK example project uses these metric names, which follow [OTel semantic conventions for database clients](https://opentelemetry.io/docs/specs/semconv/database/database-spans/):

| Metric                                | Type      | Unit | Description                     |
| ------------------------------------- | --------- | ---- | ------------------------------- |
| `db.client.operation.duration`        | Histogram | ms   | Client-measured round-trip time |
| `pinecone.server.processing.duration` | Histogram | ms   | Server processing time          |
| `db.client.operation.count`           | Counter   | --   | Total number of operations      |

## Quick start: Simple logging

The simplest way to use the listener is to log the metadata directly. This requires no additional dependencies beyond the Pinecone SDK:

```java theme={null}
import io.pinecone.clients.Pinecone;

Pinecone client = new Pinecone.Builder("PINECONE_API_KEY")
    .withResponseMetadataListener(metadata -> {
        System.out.printf("Operation: %s | Client: %dms | Server: %sms | Network: %sms | Status: %s%n",
            metadata.getOperationName(),
            metadata.getClientDurationMs(),
            metadata.getServerDurationMs(),
            metadata.getNetworkOverheadMs(),
            metadata.getStatus());
    })
    .build();
```

Once configured, every data plane operation automatically triggers the listener:

```java theme={null}
Index index = client.getIndexConnection("my-index");
index.upsert("id-1", Arrays.asList(0.1f, 0.2f, 0.3f));
// Output: Operation: upsert | Client: 47ms | Server: 40ms | Network: 7ms | Status: success
```

## Quick start: OpenTelemetry integration

To record structured metrics with OpenTelemetry, add the OTel SDK dependencies and wire a metrics recorder to the listener.

### 1. Add dependencies

Add the following to your `pom.xml`:

```xml theme={null}
<dependencies>
    <!-- Pinecone SDK -->
    <dependency>
        <groupId>io.pinecone</groupId>
        <artifactId>pinecone-client</artifactId>
        <version>LATEST</version>
    </dependency>

    <!-- OpenTelemetry SDK -->
    <dependency>
        <groupId>io.opentelemetry</groupId>
        <artifactId>opentelemetry-sdk</artifactId>
    </dependency>
    <dependency>
        <groupId>io.opentelemetry</groupId>
        <artifactId>opentelemetry-sdk-metrics</artifactId>
    </dependency>

    <!-- OTLP exporter (sends metrics to an OTel Collector or compatible backend) -->
    <dependency>
        <groupId>io.opentelemetry</groupId>
        <artifactId>opentelemetry-exporter-otlp</artifactId>
    </dependency>
</dependencies>

<!-- Use the OTel BOM to manage versions -->
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.opentelemetry</groupId>
            <artifactId>opentelemetry-bom</artifactId>
            <version>1.35.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
```

### 2. Create a metrics recorder

The SDK's [example project](https://github.com/pinecone-io/pinecone-java-client/tree/main/examples/java-otel-metrics) includes a reusable `PineconeMetricsRecorder` class you can copy into your project. It implements `ResponseMetadataListener` and records all three recommended metrics with proper OTel attributes:

```java theme={null}
import io.opentelemetry.api.common.AttributeKey;
import io.opentelemetry.api.common.Attributes;
import io.opentelemetry.api.common.AttributesBuilder;
import io.opentelemetry.api.metrics.LongCounter;
import io.opentelemetry.api.metrics.LongHistogram;
import io.opentelemetry.api.metrics.Meter;
import io.pinecone.configs.ResponseMetadata;
import io.pinecone.configs.ResponseMetadataListener;

public class PineconeMetricsRecorder implements ResponseMetadataListener {

    private static final AttributeKey<String> DB_SYSTEM = AttributeKey.stringKey("db.system");
    private static final AttributeKey<String> DB_OPERATION_NAME = AttributeKey.stringKey("db.operation.name");
    private static final AttributeKey<String> DB_NAMESPACE = AttributeKey.stringKey("db.namespace");
    private static final AttributeKey<String> PINECONE_INDEX_NAME = AttributeKey.stringKey("pinecone.index_name");
    private static final AttributeKey<String> SERVER_ADDRESS = AttributeKey.stringKey("server.address");
    private static final AttributeKey<String> STATUS = AttributeKey.stringKey("status");
    private static final AttributeKey<String> ERROR_TYPE = AttributeKey.stringKey("error.type");

    private final LongHistogram clientDurationHistogram;
    private final LongHistogram serverDurationHistogram;
    private final LongCounter operationCounter;

    public PineconeMetricsRecorder(Meter meter) {
        this.clientDurationHistogram = meter.histogramBuilder("db.client.operation.duration")
                .setDescription("Duration of Pinecone operations from client perspective")
                .setUnit("ms")
                .ofLongs()
                .build();

        this.serverDurationHistogram = meter.histogramBuilder("pinecone.server.processing.duration")
                .setDescription("Server processing time from x-pinecone-response-duration-ms header")
                .setUnit("ms")
                .ofLongs()
                .build();

        this.operationCounter = meter.counterBuilder("db.client.operation.count")
                .setDescription("Total number of Pinecone operations")
                .setUnit("{operation}")
                .build();
    }

    @Override
    public void onResponse(ResponseMetadata metadata) {
        AttributesBuilder attributesBuilder = Attributes.builder()
                .put(DB_SYSTEM, "pinecone")
                .put(DB_OPERATION_NAME, metadata.getOperationName())
                .put(PINECONE_INDEX_NAME, metadata.getIndexName())
                .put(SERVER_ADDRESS, metadata.getServerAddress())
                .put(STATUS, metadata.getStatus());

        String namespace = metadata.getNamespace();
        if (namespace != null && !namespace.isEmpty()) {
            attributesBuilder.put(DB_NAMESPACE, namespace);
        }

        if (!metadata.isSuccess() && metadata.getErrorType() != null) {
            attributesBuilder.put(ERROR_TYPE, metadata.getErrorType());
        }

        Attributes attributes = attributesBuilder.build();

        clientDurationHistogram.record(metadata.getClientDurationMs(), attributes);

        Long serverDuration = metadata.getServerDurationMs();
        if (serverDuration != null) {
            serverDurationHistogram.record(serverDuration, attributes);
        }

        operationCounter.add(1, attributes);
    }
}
```

### 3. Wire it into the Pinecone client

Initialize the OTel SDK, create the recorder, and pass it to the Pinecone client builder:

```java theme={null}
import io.opentelemetry.api.metrics.Meter;
import io.opentelemetry.sdk.OpenTelemetrySdk;
import io.opentelemetry.sdk.metrics.SdkMeterProvider;
import io.opentelemetry.sdk.metrics.export.PeriodicMetricReader;
import io.opentelemetry.exporter.otlp.metrics.OtlpGrpcMetricExporter;
import io.pinecone.clients.Pinecone;

// Set up OTel with OTLP exporter
OtlpGrpcMetricExporter exporter = OtlpGrpcMetricExporter.builder()
    .setEndpoint("http://localhost:4317")
    .build();

SdkMeterProvider meterProvider = SdkMeterProvider.builder()
    .registerMetricReader(PeriodicMetricReader.builder(exporter).build())
    .build();

OpenTelemetrySdk openTelemetry = OpenTelemetrySdk.builder()
    .setMeterProvider(meterProvider)
    .build();

// Create the metrics recorder
Meter meter = openTelemetry.getMeter("pinecone.client");
PineconeMetricsRecorder recorder = new PineconeMetricsRecorder(meter);

// Build the Pinecone client with the recorder
Pinecone client = new Pinecone.Builder("PINECONE_API_KEY")
    .withResponseMetadataListener(recorder)
    .build();

// Use the client normally -- metrics are recorded automatically
Index index = client.getIndexConnection("my-index");
index.upsert("id-1", Arrays.asList(0.1f, 0.2f, 0.3f));
index.query(3, Arrays.asList(0.1f, 0.2f, 0.3f));
```

<Tip>
  For a complete runnable example with Docker Compose, Prometheus, and Grafana, see the [java-otel-metrics example project](https://github.com/pinecone-io/pinecone-java-client/tree/main/examples/java-otel-metrics) in the SDK repository.
</Tip>

## Example: Micrometer/Prometheus

If your application uses [Micrometer](https://micrometer.io/) (common in Spring Boot), you can wire the listener to Micrometer instead of the OTel SDK:

```java theme={null}
import io.micrometer.core.instrument.MeterRegistry;
import io.micrometer.core.instrument.Timer;
import io.pinecone.clients.Pinecone;
import java.util.concurrent.TimeUnit;

Pinecone client = new Pinecone.Builder("PINECONE_API_KEY")
    .withResponseMetadataListener(metadata -> {
        Timer.builder("pinecone.client.duration")
            .tag("operation", metadata.getOperationName())
            .tag("index", metadata.getIndexName())
            .tag("status", metadata.getStatus())
            .register(meterRegistry)
            .record(metadata.getClientDurationMs(), TimeUnit.MILLISECONDS);
    })
    .build();
```

## Visualizing metrics

Once your metrics are flowing to a backend, you can build dashboards to monitor your Pinecone operations. If you're using Prometheus and Grafana, here are some useful queries:

**P50 and P95 client latency:**

```promql theme={null}
histogram_quantile(0.5, sum(rate(db_client_operation_duration_milliseconds_bucket[5m])) by (le))
histogram_quantile(0.95, sum(rate(db_client_operation_duration_milliseconds_bucket[5m])) by (le))
```

**P95 latency by operation type:**

```promql theme={null}
histogram_quantile(0.95, sum(rate(db_client_operation_duration_milliseconds_bucket[5m])) by (le, db_operation_name))
```

**Operation count by type:**

```promql theme={null}
sum by (db_operation_name) (db_client_operation_count_total)
```

## Understanding the latency breakdown

The `ResponseMetadata` object provides three timing values that help you pinpoint the source of latency issues:

| Component        | Method                   | What it measures                                                                                                                             |
| ---------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| Client duration  | `getClientDurationMs()`  | Total round-trip time from request start to response completion. Always available.                                                           |
| Server duration  | `getServerDurationMs()`  | Time the Pinecone backend spent processing the request. Extracted from the `x-pinecone-response-duration-ms` response header. May be `null`. |
| Network overhead | `getNetworkOverheadMs()` | The difference: client duration minus server duration. Includes network latency, serialization, and deserialization. May be `null`.          |

Use these values to diagnose performance issues:

* **High server duration**: The bottleneck is on the Pinecone backend. Consider optimizing your query (e.g., reducing `topK`, using metadata filters), or check the [Pinecone status page](https://status.pinecone.io/).
* **High network overhead**: The bottleneck is in the network path between your application and Pinecone. Consider deploying your application closer to your index's cloud region, or check for network issues.

## Limitations

* **Data plane operations only.** Control plane operations (e.g., creating or deleting indexes) are not currently instrumented.
* **Bulk import operations** are not yet instrumented.
* **Server duration may be unavailable.** The `getServerDurationMs()` method returns `null` if the `x-pinecone-response-duration-ms` header is not present in the response.
* **Synchronous callback.** The listener is called synchronously after the gRPC response is received. Keep implementations lightweight and non-blocking to avoid adding latency to your operations. For heavy processing, queue the metadata for async handling.
* **Exceptions are swallowed.** Exceptions thrown by the listener are logged but do not affect the operation result.

## Best practices

* **Keep listeners lightweight.** Record metrics or enqueue work -- don't do I/O or heavy computation in the callback.
* **Follow OTel semantic conventions.** Use the attribute names shown in the [recommended metrics](#recommended-metrics) table for interoperability with standard dashboards and tooling.
* **Monitor both client and server duration.** Tracking both lets you separate Pinecone backend performance from network conditions.
* **Set alerts on error rates.** Use the `status` and `error.type` attributes to build alerts for elevated error rates across operations.


# Pinecone Java SDK
Source: https://docs.pinecone.io/reference/sdks/java/overview

Install and use the Pinecone Java SDK to manage indexes and namespaces, upsert vectors, run semantic search, and call the Admin and Inference APIs from Java.

<Tip>
  For installation instructions and usage examples, see the [Pinecone Java SDK documentation](https://github.com/pinecone-io/pinecone-java-client). To report an issue or request a feature, [file an issue on GitHub](https://github.com/pinecone-io/pinecone-java-client/issues).
</Tip>

## Requirements

The Pinecone Java SDK requires Java 1.8 or later.

## SDK versions

SDK versions are pinned to specific [API versions](/reference/api/versioning). When a new API version is released, a new version of the SDK is also released.

The mappings between API versions and Java SDK versions are as follows:

| API version | SDK version |
| :---------- | :---------- |
| `2025-04`   | v5.x        |
| `2025-01`   | v4.x        |
| `2024-10`   | v3.x        |
| `2024-07`   | v2.x        |
| `2024-04`   | v1.x        |

When a new stable API version is released, you should upgrade your SDK to the latest version to ensure compatibility with the latest API changes.

## Install

To install the latest version of the [Java SDK](https://github.com/pinecone-io/pinecone-java-client), add a dependency to the current module:

```shell Java theme={null}
# Maven
<dependency>
  <groupId>io.pinecone</groupId>
  <artifactId>pinecone-client</artifactId>
  <version>5.0.0</version>
</dependency>

# Gradle
implementation "io.pinecone:pinecone-client:5.0.0"
```

Alternatively, you can download the standalone uberjar [pinecone-client-4.0.0-all.jar](https://repo1.maven.org/maven2/io/pinecone/pinecone-client/4.0.0/pinecone-client-4.0.0-all.jar), which bundles the Pinecone SDK and all dependencies together. You can include this in your classpath like you do with any third-party JAR without having to obtain the `pinecone-client` dependencies separately.

## Upgrade

<Warning>
  Before upgrading to `v4.0.0`, update all relevant code to account for the breaking changes explained [here](/release-notes/2025#2025-02-07-3).
</Warning>

If you are already using the Java SDK, upgrade the dependency in the current module to the latest version:

```shell Java theme={null}
# Maven
<dependency>
  <groupId>io.pinecone</groupId>
  <artifactId>pinecone-client</artifactId>
  <version>5.0.0</version>
</dependency>

# Gradle
implementation "io.pinecone:pinecone-client:5.0.0"
```

## Initialize

Once installed, you can import the SDK and then use an [API key](/guides/production/security-overview#api-keys) to initialize a client instance:

```Java theme={null}
import io.pinecone.clients.Pinecone;
import org.openapitools.db_control.client.model.*;

public class InitializeClientExample {
    public static void main(String[] args) {
        Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build();
    }
}
```

## Observability

The Java SDK supports capturing per-operation response metadata for all data plane operations, including client-side latency, server processing time, network overhead, and error details. You can use this metadata with [OpenTelemetry](https://opentelemetry.io/), Micrometer, or any other observability system to monitor your Pinecone usage in production.

For setup instructions and examples, see [OpenTelemetry support](/reference/sdks/java/open-telemetry).


# Reference
Source: https://docs.pinecone.io/reference/sdks/java/reference

Reference documentation for the Pinecone Java SDK, including client setup, types, and methods for managing indexes and vector data operations.



# Pinecone Node.js SDK
Source: https://docs.pinecone.io/reference/sdks/node/overview

Install and use the Pinecone Node.js and TypeScript SDK to manage indexes, upsert vectors, run semantic search, and call the Admin and Inference APIs.

<Tip>
  For installation instructions, usage examples, and reference information, see the [Pinecone Node.js SDK documentation](https://sdk.pinecone.io/typescript/). To report an issue or request a feature, [file an issue on GitHub](https://github.com/pinecone-io/pinecone-ts-client/issues).
</Tip>

## Requirements

The Pinecone Node SDK requires TypeScript 4.1 or later and Node 18.x or later.

## SDK versions

SDK versions are pinned to specific [API versions](/reference/api/versioning). When a new API version is released, a new version of the SDK is also released.

The mappings between API versions and Node.js SDK versions are as follows:

| API version | SDK version |
| :---------- | :---------- |
| `2026-04`   | v8.x        |
| `2025-10`   | v7.x        |
| `2025-04`   | v6.x        |
| `2025-01`   | v5.x        |
| `2024-10`   | v4.x        |
| `2024-07`   | v3.x        |
| `2024-04`   | v2.x        |

When a new stable API version is released, you should upgrade your SDK to the latest version to ensure compatibility with the latest API changes.

## Install

To install the latest version of the [Node.js SDK](https://github.com/pinecone-io/pinecone-ts-client), written in TypeScript, run the following command:

```Shell theme={null}
npm install @pinecone-database/pinecone
```

To check your SDK version, run the following command:

```Shell theme={null}
npm list | grep @pinecone-database/pinecone
```

## Upgrade

If you already have the Node.js SDK, upgrade to the latest version as follows:

```Shell theme={null}
npm install @pinecone-database/pinecone@latest
```

## Initialize

Once installed, you can import the library and then use an [API key](/guides/projects/manage-api-keys) to initialize a client instance:

```JavaScript theme={null}
import { Pinecone } from '@pinecone-database/pinecone';

const pc = new Pinecone({
    apiKey: 'YOUR_API_KEY'
});
```

To manage organizations, projects, API keys, and [role-based access control](/guides/production/manage-rbac), initialize an `AdminClient` with [service account](/guides/organizations/manage-service-accounts) credentials instead. This requires v8.2.0 or later:

```JavaScript theme={null}
import { AdminClient } from '@pinecone-database/pinecone';

// Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
const admin = new AdminClient();
```

You can also pass `clientId` and `clientSecret` directly to the constructor instead of setting environment variables.

## Proxy configuration

If your network setup requires you to interact with Pinecone through a proxy, you can pass a custom `ProxyAgent` from the [`undici` library](https://undici.nodejs.org/#/). Below is an example of how to construct an `undici` `ProxyAgent` that routes network traffic through a [`mitm` proxy server](https://mitmproxy.org/) while hitting Pinecone's `/indexes` endpoint.

<Note>
  The following strategy relies on Node's native [`fetch`](https://nodejs.org/docs/latest/api/globals.html#fetch) implementation, released in Node v16 and stabilized in Node v21. If you are running Node versions 18-21, you may experience issues stemming from the instability of the feature. There are currently no known issues related to proxying in Node v18+.
</Note>

```JavaScript JavaScript theme={null}
import {
  Pinecone,
  type PineconeConfiguration,
} from '@pinecone-database/pinecone';
import { Dispatcher, ProxyAgent } from 'undici';
import * as fs from 'fs';

const cert = fs.readFileSync('path/to/mitmproxy-ca-cert.pem');

const client = new ProxyAgent({
  uri: 'https://your-proxy.com',
  requestTls: {
    port: 'YOUR_PROXY_SERVER_PORT',
    ca: cert,
    host: 'YOUR_PROXY_SERVER_HOST',
  },
});

const customFetch = (
  input: string | URL | Request,
  init: RequestInit | undefined
) => {
  return fetch(input, {
    ...init,
    dispatcher: client as Dispatcher,
    keepalive: true,  # optional
  });
};

const config: PineconeConfiguration = {
  apiKey:
    'YOUR_API_KEY',
  fetchApi: customFetch,
};

const pc = new Pinecone(config);

const indexes = async () => {
  return await pc.listIndexes();
};

indexes().then((response) => {
  console.log('My indexes: ', response);
});
```


# Reference
Source: https://docs.pinecone.io/reference/sdks/node/reference

Reference documentation for the Pinecone Node.js SDK, including client setup, types, and methods for managing indexes and vector data operations.



# Pinecone Python SDK
Source: https://docs.pinecone.io/reference/sdks/python/overview

Install and use the Pinecone SDK for Pinecone Python SDK: auth, typed clients, and API operations. For installation instructions, usage examples, and.

<Tip>
  For installation instructions, usage examples, and reference information, see the [Pinecone Python SDK documentation](https://sdk.pinecone.io/python/). To report an issue or request a feature, [file an issue on GitHub](https://github.com/pinecone-io/pinecone-python-client/issues).
</Tip>

The Pinecone Python SDK is distributed on PyPI using the package name `pinecone`. By default, the `pinecone` package has a minimal set of dependencies and interacts with Pinecone via HTTP requests. However, you can install the following extras to unlock additional functionality:

* `pinecone[grpc]` adds dependencies on `grpcio` and related libraries needed to run data operations such as upserts and queries over [gRPC](https://grpc.io/) for a modest performance improvement.

* `pinecone[asyncio]` adds a dependency on `aiohttp` and enables usage of `async` methods for use with [asyncio](https://docs.python.org/3/library/asyncio.html). For more details, see [Async requests](#async-requests).

## Requirements

The Pinecone Python SDK requires Python 3.9 or later. It has been tested with CPython versions from 3.9 to 3.13.

## SDK versions

SDK versions are pinned to specific [API versions](/reference/api/versioning). When a new API version is released, a new version of the SDK is also released.

The mappings between API versions and Python SDK versions are as follows:

| API version | SDK version   |
| :---------- | :------------ |
| `2025-04`   | v7.x          |
| `2025-01`   | v6.x          |
| `2024-10`   | v5.3.x        |
| `2024-07`   | v5.0.x-v5.2.x |
| `2024-04`   | v4.x          |

When a new stable API version is released, you should upgrade your SDK to the latest version to ensure compatibility with the latest API changes.

## Install

To install the latest version of the [Python SDK](https://github.com/pinecone-io/pinecone-python-client), run the following command:

```shell theme={null}
# Install the latest version
pip install pinecone

# Install the latest version with gRPC extras
pip install "pinecone[grpc]"

# Install the latest version with asyncio extras
pip install "pinecone[asyncio]"
```

To install a specific version of the Python SDK, run the following command:

```shell pip theme={null}
# Install a specific version
pip install pinecone==<version>

# Install a specific version with gRPC extras
pip install "pinecone[grpc]"==<version>

# Install a specific version with asyncio extras
pip install "pinecone[asyncio]"==<version>
```

To check your SDK version, run the following command:

```shell pip theme={null}
pip show pinecone
```

<Note>
  To use the [Inference API](/reference/api/introduction#inference), you must be on version 5.0.0 or later.
</Note>

### Install the Pinecone Assistant Python plugin

As of Python SDK v7.0.0, the `pinecone-plugin-assistant` package is included by default. It is only necessary to install the package if you are using a version of the Python SDK prior to v7.0.0.

```shell HTTP theme={null}
pip install --upgrade pinecone pinecone-plugin-assistant
```

## Upgrade

<Warning>
  Before upgrading to `v6.0.0`, update all relevant code to account for the breaking changes explained [here](https://github.com/pinecone-io/pinecone-python-client/blob/main/docs/upgrading.md).

  Also, make sure to upgrade using the `pinecone` package name instead of `pinecone-client`; upgrading with the latter will not work as of `v6.0.0`.
</Warning>

If you already have the Python SDK, upgrade to the latest version as follows:

```shell theme={null}
# Upgrade to the latest version
pip install pinecone --upgrade

# Upgrade to the latest version with gRPC extras
pip install "pinecone[grpc]" --upgrade

# Upgrade to the latest version with asyncio extras
pip install "pinecone[asyncio]" --upgrade
```

## Initialize

Once installed, you can import the library and then use an [API key](/guides/projects/manage-api-keys) to initialize a client instance:

<CodeGroup>
  ```Python HTTP theme={null}
  from pinecone import Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")
  ```

  ```python gRPC theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")
  ```
</CodeGroup>

When [creating an index](/guides/index-data/create-an-index), import the `ServerlessSpec` or `PodSpec` class as well:

<CodeGroup>
  ```Python Serverless index theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone
  from pinecone import ServerlessSpec

  pc = Pinecone(api_key="YOUR_API_KEY")

  pc.create_index(
    name="docs-example",
    dimension=1536,
    metric="cosine",
    spec=ServerlessSpec(
      cloud="aws",
      region="us-east-1"
    )
  )
  ```

  ```Python Pod-based index theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone
  from pinecone import PodSpec

  pc = Pinecone(api_key="YOUR_API_KEY")

  pc.create_index(
    name="docs-example",
    dimension=1536,
    metric="cosine",
    spec=PodSpec(
      environment="us-west-1-gcp",
      pod_type="p1.x1",
      pods=1
    )
  )
  ```
</CodeGroup>

## Proxy configuration

If your network setup requires you to interact with Pinecone through a proxy, you will need to pass additional configuration using optional keyword parameters:

* `proxy_url`: The location of your proxy. This could be an HTTP or HTTPS URL depending on your proxy setup.
* `proxy_headers`: Accepts a python dictionary which can be used to pass any custom headers required by your proxy. If your proxy is protected by authentication, use this parameter to pass basic authentication headers with a digest of your username and password. The `make_headers` utility from `urllib3` can be used to help construct the dictionary. **Note:** Not supported with Asyncio.
* `ssl_ca_certs`: By default, the client will perform SSL certificate verification using the CA bundle maintained by Mozilla in the [`certifi`](https://pypi.org/project/certifi/) package. If your proxy is using self-signed certicates, use this parameter to specify the path to the certificate (PEM format).
* `ssl_verify`: SSL verification is enabled by default, but it is disabled when set to `False`. It is not recommened to go into production with SSL verification disabled.

<CodeGroup>
  ```python HTTP theme={null}
  from pinecone import Pinecone
  import urllib3
  from urllib3.util import make_headers

  pc = Pinecone(
      api_key="YOUR_API_KEY",
      proxy_url='https://your-proxy.com',
      proxy_headers=make_headers(proxy_basic_auth='username:password'),
      ssl_ca_certs='path/to/cert-bundle.pem'
  )
  ```

  ```python gRPC theme={null}
  from pinecone.grpc import PineconeGRPC as Pinecone
  import urllib3
  from urllib3.util import make_headers

  pc = Pinecone(
      api_key="YOUR_API_KEY",
      proxy_url='https://your-proxy.com',
      proxy_headers=make_headers(proxy_basic_auth='username:password'),
      ssl_ca_certs='path/to/cert-bundle.pem'
  )
  ```

  ```python asyncio theme={null}
  import asyncio
  from pinecone import PineconeAsyncio
  	
  async def main():
      async with PineconeAsyncio(
          api_key="YOUR_API_KEY",
          proxy_url='https://your-proxy.com',
          ssl_ca_certs='path/to/cert-bundle.pem'
      ) as pc:
          # Do async things
          await pc.list_indexes()

  asyncio.run(main())
  ```
</CodeGroup>

## Async requests

Pinecone Python SDK versions 6.0.0 and later provide `async` methods for use with [asyncio](https://docs.python.org/3/library/asyncio.html). Asyncio support makes it possible to use Pinecone with modern async web frameworks such as [FastAPI](https://fastapi.tiangolo.com/), [Quart](https://quart.palletsprojects.com/en/latest/), and [Sanic](https://sanic.dev/en/), and should significantly increase the efficiency of running requests in parallel.

Use the [`PineconeAsyncio`](https://sdk.pinecone.io/python/asyncio.html) class to create and manage indexes and the [`IndexAsyncio`](https://sdk.pinecone.io/python/asyncio.html#pinecone.db_data.IndexAsyncio) class to read and write index data. To ensure that sessions are properly closed, use the `async with` syntax when creating `PineconeAsyncio` and `IndexAsyncio` objects.

<CodeGroup>
  ```python Manage indexes theme={null}
  # pip install "pinecone[asyncio]"
  import asyncio
  from pinecone import PineconeAsyncio, ServerlessSpec

  async def main():
      async with PineconeAsyncio(api_key="YOUR_API_KEY") as pc:
          if not await pc.has_index(index_name):
              desc = await pc.create_index(
                  name="docs-example",
                  dimension=1536,
                  metric="cosine",
                  spec=ServerlessSpec(
                      cloud="aws",
                      region="us-east-1"
                  ),
                  deletion_protection="disabled",
                  tags={
                      "environment": "development"
                  }
              )

  asyncio.run(main())
  ```

  ```python Read and write index data theme={null}
  # pip install "pinecone[asyncio]"
  import asyncio
  from pinecone import Pinecone

  async def main():
      pc = Pinecone(api_key="YOUR_API_KEY")
      async with pc.IndexAsyncio(host="INDEX_HOST") as idx:
          await idx.upsert_records(
              namespace="example-namespace",
              records=[
                  {
                      "id": "1",
                      "title": "The Great Gatsby",
                      "author": "F. Scott Fitzgerald",
                      "description": "The story of the mysteriously wealthy Jay Gatsby and his love for the beautiful Daisy Buchanan.",
                      "year": 1925,
                  },
                  {
                      "id": "2",
                      "title": "To Kill a Mockingbird",
                      "author": "Harper Lee",
                      "description": "A young girl comes of age in the segregated American South and witnesses her father's courageous defense of an innocent black man.",
                      "year": 1960,
                  },
                  {
                      "id": "3",
                      "title": "1984",
                      "author": "George Orwell",
                      "description": "In a dystopian future, a totalitarian regime exercises absolute control through pervasive surveillance and propaganda.",
                      "year": 1949,
                  },
              ]
          )

  asyncio.run(main())
  ```
</CodeGroup>

## Query across namespaces

Each query is limited to a single [namespace](/guides/index-data/indexing-overview#namespaces). However, the Pinecone Python SDK provides a `query_namespaces` utility method to run a query in parallel across multiple namespaces in an index and then merge the result sets into a single ranked result set with the `top_k` most relevant results.

The `query_namespaces` method accepts most of the same arguments as `query` with the addition of a required `namespaces` parameter.

<Tabs>
  <Tab title="Python SDK without gRPC">
    When using the Python SDK without gRPC extras, to get good performance, it is important to set values for the `pool_threads` and `connection_pool_maxsize` properties on the index client. The `pool_threads` setting is the number of threads available to execute requests, while `connection_pool_maxsize` is the number of cached http connections that will be held. Since these tasks are not computationally heavy and are mainly i/o bound, it should be okay to have a high ratio of threads to cpus.

    The combined results include the sum of all read unit usage used to perform the underlying queries for each namespace.

    ```python Python theme={null}
    from pinecone import Pinecone

    pc = Pinecone(api_key="YOUR_API_KEY")
    index = pc.Index(
        name="docs-example",
        pool_threads=50,             # <-- make sure to set these
        connection_pool_maxsize=50,  # <-- make sure to set these
    )

    query_vec = [ 0.1, ...] # an embedding vector with same dimension as the index
    combined_results = index.query_namespaces(
        vector=query_vec,
        namespaces=['ns1', 'ns2', 'ns3', 'ns4'],
        metric="cosine",
        top_k=10,
        include_values=False,
        include_metadata=True,
        filter={"genre": { "$eq": "comedy" }},
        show_progress=False,
    )

    for scored_vec in combined_results.matches:
        print(scored_vec)
    print(combined_results.usage)
    ```
  </Tab>

  <Tab title="Python SDK with gRPC">
    When using the Python SDK with gRPC extras, there is no need to set the `connection_pool_maxsize` because grpc makes efficient use of open connections by default.

    ```python Python theme={null}
    from pinecone.grpc import PineconeGRPC

    pc = PineconeGRPC(api_key="YOUR_API_KEY")
    index = pc.Index(
        name="docs-example",
        pool_threads=50, # <-- make sure to set this
    )

    query_vec = [ 0.1, ...] # an embedding vector with same dimension as the index
    combined_results = index.query_namespaces(
        vector=query_vec,
        namespaces=['ns1', 'ns2', 'ns3', 'ns4'],
        metric="cosine",
        top_k=10,
        include_values=False,
        include_metadata=True,
        filter={"genre": { "$eq": "comedy" }},
        show_progress=False,
    )

    for scored_vec in combined_results.matches:
        print(scored_vec)
    print(combined_results.usage)
    ```
  </Tab>
</Tabs>

## Upsert from a dataframe

To quickly ingest data when using the [Python SDK](/reference/sdks/python/overview), use the `upsert_from_dataframe` method. The method includes retry logic and`batch_size`, and is performant especially with Parquet file data sets.

The following example upserts the `uora_all-MiniLM-L6-bm25` dataset as a dataframe.

```Python Python theme={null}
from pinecone import Pinecone, ServerlessSpec
from pinecone_datasets import list_datasets, load_dataset

pc = Pinecone(api_key="API_KEY")

dataset = load_dataset("quora_all-MiniLM-L6-bm25")

pc.create_index(
  name="docs-example",
  dimension=384,
  metric="cosine",
  spec=ServerlessSpec(
    cloud="aws",
    region="us-east-1"
  )
)

# To get the unique host for an index, 
# see https://docs.pinecone.io/guides/manage-data/target-an-index
index = pc.Index(host="INDEX_HOST")

index.upsert_from_dataframe(dataset.drop(columns=["blob"]))
```


# Reference
Source: https://docs.pinecone.io/reference/sdks/python/reference

Reference documentation for the Pinecone Python SDK, including client setup, types, and methods for managing indexes and vector data operations.



# Spark-Pinecone connector
Source: https://docs.pinecone.io/reference/tools/pinecone-spark-connector

Pinecone data tools: Use the connector to efficiently create, ingest, and update vector embeddings at scale with Databricks and Pinecone.

Use the [`spark-pinecone` connector](https://github.com/pinecone-io/spark-pinecone/) to efficiently create, ingest, and update [vector embeddings](https://www.pinecone.io/learn/vector-embeddings/) at scale with [Databricks and Pinecone](/integrations/databricks).

## Install the Spark-Pinecone connector

<Tabs>
  <Tab title="Databricks platform">
    1. [Install the Spark-Pinecone connector as a library](https://docs.databricks.com/en/libraries/cluster-libraries.html#install-a-library-on-a-cluster).
    2. Configure the library as follows:
       1. Select **File path/S3** as the **Library Source**.

       2. Enter the S3 URI for the Pinecone assembly JAR file:

          ```
          s3://pinecone-jars/1.1.0/spark-pinecone-uberjar.jar  
          ```

          <Note>
            Databricks platform users must use the Pinecone assembly jar listed above to ensure that the proper dependecies are installed.
          </Note>

       3. Click **Install**.
  </Tab>

  <Tab title="Databricks on AWS">
    1. [Install the Spark-Pinecone connector as a library](https://docs.databricks.com/en/libraries/cluster-libraries.html#install-a-library-on-a-cluster).
    2. Configure the library as follows:
       1. Select **File path/S3** as the **Library Source**.

       2. Enter the S3 URI for the Pinecone assembly JAR file:

          ```
          s3://pinecone-jars/1.1.0/spark-pinecone-uberjar.jar  
          ```

       3. Click **Install**.
  </Tab>

  <Tab title="Databricks on GCP / Azure">
    1. [Install the Spark-Pinecone connector as a library](https://docs.databricks.com/en/libraries/cluster-libraries.html#install-a-library-on-a-cluster).
    2. Configure the library as follows:
       1. [Download the Pinecone assembly JAR file](https://repo1.maven.org/maven2/io/pinecone/spark-pinecone_2.12/1.1.0/).
       2. Select **Workspace** as the **Library Source**.
       3. Upload the JAR file.
       4. Click **Install**.
  </Tab>
</Tabs>

## Batch upsert

To batch upsert embeddings to Pinecone:

<CodeGroup>
  ```python Python theme={null}
  from pyspark import SparkConf
  from pyspark.sql import SparkSession
  from pyspark.sql.types import StructType, StructField, ArrayType, FloatType, StringType, LongType

  # Your API key and index name
  api_key = "PINECONE_API_KEY"
  index_name = "PINECONE_INDEX_NAME"
  source_tag = "PINECONE_SOURCE_TAG"

  COMMON_SCHEMA = StructType([
      StructField("id", StringType(), False),
      StructField("namespace", StringType(), True),
      StructField("values", ArrayType(FloatType(), False), False),
      StructField("metadata", StringType(), True),
      StructField("sparse_values", StructType([
          StructField("indices", ArrayType(LongType(), False), False),
          StructField("values", ArrayType(FloatType(), False), False)
      ]), True)
  ])

  # Initialize Spark
  spark = SparkSession.builder.getOrCreate()

  # Read the file and apply the schema
  df = spark.read \
      .option("multiLine", value = True) \
      .option("mode", "PERMISSIVE") \
      .schema(COMMON_SCHEMA) \
      .json("src/test/resources/sample.jsonl")

  # Show if the read was successful
  df.show()

  # Write the dataFrame to Pinecone in batches 
  df.write \
      .option("pinecone.apiKey", api_key) \
      .option("pinecone.indexName", index_name) \
      .option("pinecone.sourceTag", source_tag) \
      .format("io.pinecone.spark.pinecone.Pinecone") \
      .mode("append") \
      .save()
  ```

  ```scala Scala theme={null}
  import io.pinecone.spark.pinecone.{COMMON_SCHEMA, PineconeOptions}
  import org.apache.spark.SparkConf
  import org.apache.spark.sql.{SaveMode, SparkSession}

  object MainApp extends App {
    // Your API key and index name
    val apiKey = "PINECONE_API_KEY"
    val indexName = "PINECONE_INDEX_NAME"
    val sourceTag = "PINECONE_SOURCE_TAG"

    // Configure Spark to run locally with all available cores
    val conf = new SparkConf()
      .setMaster("local[*]")

    // Create a Spark session with the defined configuration
    val spark = SparkSession.builder().config(conf).getOrCreate()

    // Read the JSON file into a DataFrame, applying the COMMON_SCHEMA
    val df = spark.read
      .option("multiLine", value = true)
      .option("mode", "PERMISSIVE")
      .schema(COMMON_SCHEMA)
      .json("src/test/resources/sample.jsonl") // path to sample.jsonl

    // Define Pinecone options as a Map
    val pineconeOptions = Map(
      PineconeOptions.PINECONE_API_KEY_CONF -> apiKey,
      PineconeOptions.PINECONE_INDEX_NAME_CONF -> indexName,
      PineconeOptions.PINECONE_SOURCE_TAG_CONF -> sourceTag
    )

    // Show if the read was successful
    df.show(df.count().toInt)
    
    // Write the DataFrame to Pinecone using the defined options in batches
    df.write
      .options(pineconeOptions)
      .format("io.pinecone.spark.pinecone.Pinecone")
      .mode(SaveMode.Append)
      .save()
  }
  ```
</CodeGroup>

<Tip>
  For a guide on how to set up batch upserts, refer to the [Databricks integration page](/integrations/databricks#setup-guide).
</Tip>

## Stream upsert

To stream upsert embeddings to Pinecone:

<CodeGroup>
  ```python Python theme={null}
  from pyspark.sql import SparkSession
  from pyspark.sql.types import StructType, StructField, ArrayType, FloatType, StringType, LongType
  import os

  # Your API key and index name
  api_key = "PINECONE_API_KEY"
  index_name = "PINECONE_INDEX_NAME"
  source_tag = "PINECONE_SOURCE_TAG"

  COMMON_SCHEMA = StructType([
      StructField("id", StringType(), False),
      StructField("namespace", StringType(), True),
      StructField("values", ArrayType(FloatType(), False), False),
      StructField("metadata", StringType(), True),
      StructField("sparse_values", StructType([
          StructField("indices", ArrayType(LongType(), False), False),
          StructField("values", ArrayType(FloatType(), False), False)
      ]), True)
  ])

  # Initialize Spark session
  spark = SparkSession.builder \
      .appName("StreamUpsertExample") \
      .config("spark.sql.shuffle.partitions", 3) \
      .master("local") \
      .getOrCreate()

  # Read the stream of JSON files, applying the schema from the input directory
  lines = spark.readStream \
      .option("multiLine", True) \
      .option("mode", "PERMISSIVE") \
      .schema(COMMON_SCHEMA) \
      .json("path/to/input/directory/")

  # Write the stream to Pinecone using the defined options
  upsert = lines.writeStream \
      .format("io.pinecone.spark.pinecone.Pinecone") \
      .option("pinecone.apiKey", api_key) \
      .option("pinecone.indexName", index_name) \
      .option("pinecone.sourceTag", source_tag) \
      .option("checkpointLocation", "path/to/checkpoint/dir") \
      .outputMode("append") \
      .start()

  upsert.awaitTermination()
  ```

  ```scala Scala theme={null}
  import io.pinecone.spark.pinecone.{COMMON_SCHEMA, PineconeOptions}
  import org.apache.spark.SparkConf
  import org.apache.spark.sql.{SaveMode, SparkSession}

  object MainApp extends App {
    // Your API key and index name
    val apiKey = "PINECONE_API_KEY"
    val indexName = "PINECONE_INDEX_NAME"

    // Create a Spark session
    val spark = SparkSession.builder()
      .appName("StreamUpsertExample")
      .config("spark.sql.shuffle.partitions", 3)
      .master("local")
      .getOrCreate()

    // Read the JSON files into a DataFrame, applying the COMMON_SCHEMA from input directory
    val lines = spark.readStream
      .option("multiLine", value = true)
      .option("mode", "PERMISSIVE")
      .schema(COMMON_SCHEMA)
      .json("path/to/input/directory/")

    // Define Pinecone options as a Map
    val pineconeOptions = Map(
      PineconeOptions.PINECONE_API_KEY_CONF -> System.getenv("PINECONE_API_KEY"),
      PineconeOptions.PINECONE_INDEX_NAME_CONF -> System.getenv("PINECONE_INDEX"),
      PineconeOptions.PINECONE_SOURCE_TAG_CONF -> System.getenv("PINECONE_SOURCE_TAG")
    )

    // Write the stream to Pinecone using the defined options
    val upsert = lines
      .writeStream
      .format("io.pinecone.spark.pinecone.Pinecone")
      .options(pineconeOptions)
      .option("checkpointLocation", "path/to/checkpoint/dir")
      .outputMode("append")
      .start()

    upsert.awaitTermination()
  }
  ```
</CodeGroup>

## Learn more

* [Spark-Pinecone connector setup guide](/integrations/databricks#setup-guide)
* [GitHub](https://github.com/pinecone-io/spark-pinecone)


# Access your invoices
Source: https://docs.pinecone.io/guides/assistant/admin/access-your-invoices

View, download, and manage your Pinecone billing invoices from the console, including past invoice history, payment status, and PDF exports.

You can access your billing history and invoices in the Pinecone console:

1. Go to [**Settings > Billing > Overview**](https://app.pinecone.io/organizations/-/settings/billing).
2. Scroll down to the **Payment history and invoices** section.
3. For each billing period, you can download the invoice by clicking the **Download** button.

Each invoice includes line items for the services used during the billing period. If the total cost of that usage is below the monthly minimum, the invoice also includes a line item covering the rest of the minimum usage commitment.


# Change your payment method
Source: https://docs.pinecone.io/guides/assistant/admin/change-payment-method

Update the credit card or payment method on file for your Pinecone organization to keep billing details current and avoid failed charges.

You can pay for the [Standard and Enterprise plans](https://www.pinecone.io/pricing/) with a credit/debit card or through the AWS Marketplace, Microsoft Marketplace, or Google Cloud Marketplace. This page describes how to switch between these payment methods.

<Note>
  To change your payment method, you must be an [organization owner or billing admin](/guides/organizations/understanding-organizations#organization-roles).
</Note>

<Note>
  The [Builder plan](https://www.pinecone.io/pricing/) is available with credit/debit card billing only and is not supported through cloud marketplaces.
</Note>

To switch a Builder-plan organization to marketplace billing, first [upgrade to the Standard or Enterprise plan](/guides/organizations/manage-billing/upgrade-billing-plan) using the marketplace subscription flow.

## Credit card → marketplace

To change from credit card to marketplace billing, you'll need to:

1. Create a new Pinecone organization through the marketplace
2. Migrate your existing projects to the new Pinecone organization
3. Add your team members to the new Pinecone organization
4. Downgrade your original Pinecone organization once migration is complete

<Tabs>
  <Tab title="Credit card → Google Cloud">
    To change from paying with a credit card to paying through the Google Cloud Marketplace, do the following:

    1. Subscribe to Pinecone in the Google Cloud Marketplace:

       1. In the Google Cloud Marketplace, go to the [Pinecone listing](https://console.cloud.google.com/marketplace/product/pinecone-public/pinecone).
       2. Click **Subscribe**.
       3. On the **Order Summary** page, select a billing account, accept the terms and conditions, and click **Subscribe**.

          <Note>The billing unit listed does not reflect the actual cost or metering of costs for Pinecone. See the [Pinecone Pricing page](https://www.pinecone.io/pricing/) for accurate details.</Note>
       4. On the **Your order request has been sent to Pinecone** modal, click **Sign up with Pinecone**. This takes you to a Google-specific Pinecone sign-up page.
       5. Sign up using the same authentication method as your existing Pinecone organization.

    2. Create a new Pinecone organization and connect it to your Google Cloud Marketplace account:

       1. On the **Connect GCP to Pinecone** page, choose **Select an organization > + Create New Organization**.

          <Note>If you see a message saying that the subscription is still in process, wait a few minutes, refresh the page, and proceed only when the message has disappeared.</Note>
       2. Enter the name of the new organization and click **Connect to Pinecone**.
       3. On the **Confirm GCP marketplace Connection** modal, click **Connect**. This takes you to your new organization in the Pinecone console.

    3. Migrate your projects to the new Pinecone organization:

       1. In the Pinecone console, go to [**Settings > Access > Members**](https://app.pinecone.io/organizations/-/settings/access/members).
       2. Make sure the **Owner** email address for your original organization is set as an **Owner** or **Billing Admin** for your new organization. This allows Pinecone to verify that both the original and new organizations are owned by the same person.
       3. Go to [**Settings > Manage**](https://app.pinecone.io/organizations/-/settings/manage) and copy your new organization ID.
       4. Go to [**Settings > Support > Tickets**](https://app.pinecone.io/organizations/-/settings/support/ticket/create).
       5. For **Ticket category**, select **Project or Organization Management**.
       6. For **Subject**, enter "Migrate projects to a new organization".
       7. For **Description**, enter the following:

          ```
          I am changing my payment method from credit card to Google Cloud Marketplace. 
          Please migrate my projects to my new organization: `<NEW_ORG_ID>`
          ```
       8. Click **Submit**.

    4. Add your team members to the new organization:

       1. In the Pinecone console, go to [**Settings > Access > Members**](https://app.pinecone.io/organizations/-/settings/access/members).
       2. [Add your team members to the new organization](/guides/organizations/manage-organization-members#add-a-member-to-an-organization).

    5. Downgrade your original Pinecone organization:

       <Note>
         Do not downgrade your original organization until you receive a confirmation that Pinecone has finished the migration to your new organization.
       </Note>

       1. In the Pinecone console, go to your original organization.
       2. Go to **Settings > Billing > Plans**.
       3. In the **Starter** section, click **Downgrade**.
       4. Click **Confirm downgrade**.

    Going forward, your usage of Pinecone will be billed through the Google Cloud Marketplace.

    <Warning>
      You can [delete your original organization](/troubleshooting/delete-your-organization). However, before deleting, make sure to [download your past invoices](/guides/organizations/manage-billing/access-your-invoices) since you will lose access to them once the organization is deleted.
    </Warning>
  </Tab>

  <Tab title="Credit card → AWS">
    To change from paying with a credit card to paying through the AWS Marketplace, do the following:

    1. Subscribe to Pinecone in the AWS Marketplace:

       1. In the AWS Marketplace, go to the [Pinecone listing](https://aws.amazon.com/marketplace/pp/prodview-xhgyscinlz4jk).
       2. Click **View purchase options**.
       3. On the **Subscribe to Pinecone Vector Database** page, review the offer and then click **Subscribe**.

          <Note>The billing unit listed does not reflect the actual cost or metering of costs for Pinecone. See the [Pinecone Pricing page](https://www.pinecone.io/pricing/) for accurate details.</Note>
       4. You'll see a message stating that your subscription is in process. Click **Set up your account**. This takes you to an AWS-specific Pinecone sign-up page.
       5. Sign up using the same authentication method as your existing Pinecone organization.

    2. Create a new Pinecone organization and connect it to your AWS account:

       1. On the **Connect AWS to Pinecone** page, choose **Select an organization > + Create New Organization**.

       <Note>If you see a message saying that the subscription is still in process, wait a few minutes, refresh the page, and proceed only when the message has disappeared.</Note>

       1. Enter the name of the new organization and click **Connect to Pinecone**.
       2. On the **Confirm AWS Marketplace Connection** modal, click **Connect**. This takes you to your new organization in the Pinecone console.

    3. Migrate your projects to the new Pinecone organization:

       1. In the Pinecone console, go to [**Settings > Access > Members**](https://app.pinecone.io/organizations/-/settings/access/members).
       2. Make sure the **Owner** email address for your original organization is set as an **Owner** or **Billing Admin** for your new organization. This allows Pinecone to verify that both the original and new organizations are owned by the same person.
       3. Go to [**Settings > Manage**](https://app.pinecone.io/organizations/-/settings/manage) and copy your new organization ID.
       4. Go to [**Settings > Support > Tickets**](https://app.pinecone.io/organizations/-/settings/support/ticket/create).
       5. For **Ticket category**, select **Project or Organization Management**.
       6. For **Subject**, enter "Migrate projects to a new organization".
       7. For **Description**, enter the following:

          ```
          I am changing my payment method from credit card to Google Cloud Marketplace. 
          Please migrate my projects to my new organization: `<NEW_ORG_ID>`
          ```
       8. Click **Submit**.

    4. Add your team members to the new organization:

       1. In the Pinecone console, go to [**Settings > Access > Members**](https://app.pinecone.io/organizations/-/settings/access/members).
       2. [Add your team members to the new organization](/guides/organizations/manage-organization-members#add-a-member-to-an-organization).

    5. Downgrade your original Pinecone organization:

       <Note>
         Do not downgrade your original organization until you receive a confirmation that Pinecone has finished the migration to your new organization.
       </Note>

       1. In the Pinecone console, go to your original organization.
       2. Go to **Settings > Billing > Plans**.
       3. In the **Starter** section, click **Downgrade**.
       4. Click **Confirm downgrade**.

    Going forward, your usage of Pinecone will be billed through the AWS Marketplace.

    <Warning>
      You can [delete your original organization](/troubleshooting/delete-your-organization). However, before deleting, make sure to [download your past invoices](/guides/organizations/manage-billing/access-your-invoices) since you will lose access to them once the organization is deleted.
    </Warning>
  </Tab>

  <Tab title="Credit card → Microsoft">
    To change from paying with a credit card to paying through the Microsoft Marketplace, do the following:

    1. Subscribe to Pinecone in the Microsoft Marketplace:

       1. In the Microsoft Marketplace, go to the [Pinecone listing](https://marketplace.microsoft.com/product/saas/pineconesystemsinc1688761585469.pineconesaas).
       2. Click **Get it now**.
       3. Select the **Pinecone - Pay As You Go** plan.
       4. Click **Subscribe**.
       5. On the **Subscribe to Pinecone** page, select the required details and click **Review + subscribe**.

          <Note>The billing unit listed does not reflect the actual cost or metering of costs for Pinecone. See the [Pinecone Pricing page](https://www.pinecone.io/pricing/) for accurate details.</Note>
       6. Click **Subscribe**.
       7. After the subscription is approved, click **Configure account now**. This redirects you to an Microsoft-specific Pinecone login page.
       8. Sign up using the same authentication method as your existing Pinecone organization.

    2. Create a new Pinecone organization and connect it to your Microsoft Marketplace account:

       1. On the **Connect Azure to Pinecone** page, choose **Select an organization > + Create New Organization**.

       <Note>If you see a message saying that the subscription is still in process, wait a few minutes, refresh the page, and proceed only when the message has disappeared.</Note>

       1. Enter the name of the new organization and click **Connect to Pinecone**.
       2. On the **Connect Azure marketplace connection** modal, click **Connect**. This takes you to your new organization in the Pinecone console.

    3. Migrate your projects to the new Pinecone organization:

       1. In the Pinecone console, go to [**Settings > Access > Members**](https://app.pinecone.io/organizations/-/settings/access/members).
       2. Make sure the **Owner** email address for your original organization is set as an **Owner** or **Billing Admin** for your new organization. This allows Pinecone to verify that both the original and new organizations are owned by the same person.
       3. Go to [**Settings > Manage**](https://app.pinecone.io/organizations/-/settings/manage) and copy your new organization ID.
       4. Go to [**Settings > Support > Tickets**](https://app.pinecone.io/organizations/-/settings/support/ticket/create).
       5. For **Ticket category**, select **Project or Organization Management**.
       6. For **Subject**, enter "Migrate projects to a new organization".
       7. For **Description**, enter the following:

          ```
          I am changing my payment method from credit card to Microsoft Marketplace. 
          Please migrate my projects to my new organization: `<NEW_ORG_ID>`
          ```
       8. Click **Submit**.

    4. Add your team members to the new organization:

       1. In the Pinecone console, go to [**Settings > Access > Members**](https://app.pinecone.io/organizations/-/settings/access/members).
       2. [Add your team members to the new organization](/guides/organizations/manage-organization-members#add-a-member-to-an-organization).

    5. Downgrade your original Pinecone organization:

       <Note>
         Do not downgrade your original organization until you receive a confirmation that Pinecone has finished the migration to your new organization.
       </Note>

       1. In the Pinecone console, go to your original organization.
       2. Go to **Settings > Billing > Plans**.
       3. In the **Starter** section, click **Downgrade**.
       4. Click **Confirm downgrade**.

    Going forward, your usage of Pinecone will be billed through the Microsoft Marketplace.

    <Warning>
      You can [delete your original organization](/troubleshooting/delete-your-organization). However, before deleting, make sure to [download your past invoices](/guides/organizations/manage-billing/access-your-invoices) since you will lose access to them once the organization is deleted.
    </Warning>
  </Tab>
</Tabs>

## Marketplace → credit card

To change from marketplace billing to credit card, you'll need to:

1. Create a new organization in your Pinecone account
2. Upgrade the new organization to the Standard or Enterprise plan
3. Migrate your existing projects to the new organization
4. Add your team members to the new organization
5. Downgrade your original organization once migration is complete

<Tabs>
  <Tab title="Google Cloud → credit card">
    To change from paying through the Google Cloud Marketplace to paying with a credit card, do the following:

    1. Create a new organization in your Pinecone account:

       1. In the Pinecone console, go to [**Organizations**](https://app.pinecone.io/organizations/-/settings/account/organizations).
       2. Click **+ Create organization**.
       3. Enter the name of the new organization and click **Create**.

    2. Upgrade the new organization:

       1. Go to [Settings > Billing > Plans](https://app.pinecone.io/organizations/-/settings/billing/plans).
       2. Click **Upgrade** in the **Standard** or **Enterprise** plan section.
       3. Click **Credit / Debit card**.
       4. Enter your credit card information.
       5. Click **Upgrade**.

       The new organization is now set up with credit card billing. You'll use this organization after completing the rest of this process.

    3. Migrate your projects to the new Pinecone organization:

       1. Go to [**Settings > Manage**](https://app.pinecone.io/organizations/-/settings/manage) and copy your new organization ID.
       2. Go to [**Settings > Support > Tickets**](https://app.pinecone.io/organizations/-/settings/support/ticket/create).
       3. For **Ticket category**, select **Project or Organization Management**.
       4. For **Subject**, enter "Migrate projects to a new organization".
       5. For **Description**, enter the following:

          ```
          I am changing my payment method from Google Cloud Marketplace to credit card. 
          Please migrate my projects to my new organization: `<NEW_ORG_ID>`
          ```
       6. Click **Submit**.

    4. Add your team members to the new organization:

       1. In the Pinecone console, go to [**Settings > Access > Members**](https://app.pinecone.io/organizations/-/settings/access/members).
       2. [Add your team members to the new organization](/guides/organizations/manage-organization-members#add-a-member-to-an-organization).

    5. Downgrade your original Pinecone organization:

       <Note>
         Do not downgrade your original organization until you receive a confirmation that Pinecone has finished the migration to your new organization.
       </Note>

       1. In the Pinecone console, go to your original organization.
       2. Go to [**Settings > Billing > Plans**](https://app.pinecone.io/organizations/-/settings/billing/plans).
       3. In the **Starter** section, click **Downgrade**.
       4. Click **Confirm downgrade**.
       5. On the **Continue your downgrade on the GCP marketplace** modal, click **Continue to marketplace**. This takes you to your orders page in Google Cloud Marketplace.
       6. [Cancel the order](https://cloud.google.com/marketplace/docs/manage-billing#saas-products) for your original organization.

          <Tip>
            If you don't see the order, check that the correct billing account is selected.
          </Tip>

    Going forward, you'll use your new organization and your usage will be billed through the credit card you provided.

    <Warning>
      You can [delete your original organization](/troubleshooting/delete-your-organization). However, before deleting, make sure to [download your past invoices](/guides/organizations/manage-billing/access-your-invoices) since you will lose access to them once the organization is deleted.
    </Warning>
  </Tab>

  <Tab title="AWS → credit card">
    To change from paying through the AWS Marketplace to paying with a credit card, do the following:

    1. Create a new organization in your Pinecone account:

       1. In the Pinecone console, go to [**Organizations**](https://app.pinecone.io/organizations/-/settings/account/organizations).
       2. Click **+ Create organization**.
       3. Enter the name of the new organization and click **Create**.

    2. Upgrade the new organization:

       1. Go to [Settings > Billing > Plans](https://app.pinecone.io/organizations/-/settings/billing/plans).
       2. Click **Upgrade** in the **Standard** or **Enterprise** plan section.
       3. Click **Credit / Debit card**.
       4. Enter your credit card information.
       5. Click **Upgrade**.

       The new organization is now set up with credit card billing. You'll use this organization after completing the rest of this process.

    3. Migrate your projects to the new Pinecone organization:

       1. Go to [**Settings > Manage**](https://app.pinecone.io/organizations/-/settings/manage) and copy your new organization ID.
       2. Go to [**Settings > Support > Tickets**](https://app.pinecone.io/organizations/-/settings/support/ticket/create).
       3. For **Ticket category**, select **Project or Organization Management**.
       4. For **Subject**, enter "Migrate projects to a new organization".
       5. For **Description**, enter the following:

          ```
          I am changing my payment method from AWS Marketplace to credit card. 
          Please migrate my projects to my new organization: `<NEW_ORG_ID>`
          ```
       6. Click **Submit**.

    4. Add your team members to the new organization:

       1. In the Pinecone console, go to [**Settings > Access > Members**](https://app.pinecone.io/organizations/-/settings/access/members).
       2. [Add your team members to the new organization](/guides/organizations/manage-organization-members#add-a-member-to-an-organization).

    5. Downgrade your original Pinecone organization:

       <Note>
         Do not downgrade your original organization until you receive a confirmation that Pinecone has finished the migration to your new organization.
       </Note>

       1. In the Pinecone console, go to your original organization.
       2. Go to [**Settings > Billing > Plans**](https://app.pinecone.io/organizations/-/settings/billing/plans).
       3. In the **Starter** section, click **Downgrade**.
       4. Click **Confirm downgrade**.
       5. On the **Continue your downgrade on the AWS marketplace** modal, click **Continue to marketplace**. This takes you to the [Manage subscriptions](https://console.aws.amazon.com/marketplace) page in the AWS Marketplace.
       6. [Cancel the subscription](https://docs.aws.amazon.com/marketplace/latest/buyerguide/cancel-subscription.html#cancel-saas-subscription) to Pinecone.

    Going forward, you'll use your new organization and your usage will be billed through the credit card you provided.

    <Warning>
      You can [delete your original organization](/troubleshooting/delete-your-organization). However, before deleting, make sure to [download your past invoices](/guides/organizations/manage-billing/access-your-invoices) since you will lose access to them once the organization is deleted.
    </Warning>
  </Tab>

  <Tab title="Microsoft → credit card">
    To change from paying through the Microsoft Marketplace to paying with a credit card, do the following:

    1. Create a new organization in your Pinecone account:

       1. In the Pinecone console, go to [**Organizations**](https://app.pinecone.io/organizations/-/settings/account/organizations).
       2. Click **+ Create organization**.
       3. Enter the name of the new organization and click **Create**.

    2. Upgrade the new organization:

       1. Go to [Settings > Billing > Plans](https://app.pinecone.io/organizations/-/settings/billing/plans).
       2. Click **Upgrade** in the **Standard** or **Enterprise** plan section.
       3. Click **Credit / Debit card**.
       4. Enter your credit card information.
       5. Click **Upgrade**.

       The new organization is now set up with credit card billing. You'll use this organization after completing the rest of this process.

    3. Migrate your projects to the new Pinecone organization:

       1. Go to [**Settings > Manage**](https://app.pinecone.io/organizations/-/settings/manage) and copy your new organization ID.
       2. Go to [**Settings > Support > Tickets**](https://app.pinecone.io/organizations/-/settings/support/ticket/create).
       3. For **Ticket category**, select **Project or Organization Management**.
       4. For **Subject**, enter "Migrate projects to a new organization".
       5. For **Description**, enter the following:

          ```
          I am changing my payment method from Microsoft Marketplace to credit card. 
          Please migrate my projects to my new organization: `<NEW_ORG_ID>`
          ```
       6. Click **Submit**.

    4. Add your team members to the new organization:

       1. In the Pinecone console, go to [**Settings > Access > Members**](https://app.pinecone.io/organizations/-/settings/access/members).
       2. [Add your team members to the new organization](/guides/organizations/manage-organization-members#add-a-member-to-an-organization).

    5. Downgrade your original Pinecone organization:

       <Note>
         Do not downgrade your original organization until you receive a confirmation that Pinecone has finished the migration to your new organization.
       </Note>

       1. In the Pinecone console, go to your original organization.
       2. Go to [**Settings > Billing > Plans**](https://app.pinecone.io/organizations/-/settings/billing/plans).
       3. In the **Starter** section, click **Downgrade**.
       4. Click **Confirm downgrade**.
       5. On the **Continue your downgrade on Azure marketplace** modal, click **Continue to marketplace**.
       6. On the **SaaS** page, click your subscription to Pinecone.
       7. Click **Cancel subscription**.
       8. Confirm the cancellation.

    Going forward, you'll use your new organization and your usage will be billed through the credit card you provided.

    <Warning>
      You can [delete your original organization](/troubleshooting/delete-your-organization). However, before deleting, make sure to [download your past invoices](/guides/organizations/manage-billing/access-your-invoices) since you will lose access to them once the organization is deleted.
    </Warning>
  </Tab>
</Tabs>

## Marketplace → marketplace

To change from one marketplace to another, you'll need to:

1. Subscribe to Pinecone in the new marketplace
2. Connect your existing org to the new marketplace
3. Cancel your subscription in the old marketplace

<Tabs>
  <Tab title="Any marketplace → Google Cloud">
    To change to a Google Cloud Marketplace billing account, do the following:

    1. Subscribe to Pinecone in the Google Cloud Marketplace:

       1. In the Google Cloud Marketplace, go to the [Pinecone listing](https://console.cloud.google.com/marketplace/product/pinecone-public/pinecone).
       2. Click **Subscribe**.
       3. On the **Order Summary** page, select a billing account, accept the terms and conditions, and click **Subscribe**.

          <Note>The billing unit listed does not reflect the actual cost or metering of costs for Pinecone. See the [Pinecone Pricing page](https://www.pinecone.io/pricing/) for accurate details.</Note>
       4. On the **Your order request has been sent to Pinecone** modal, click **Sign up with Pinecone**. This takes you to a Google-specific Pinecone login page.
       5. Log in to your Pinecone account. Use the same authentication method as your existing Pinecone organization.

    2. Connect your existing org to your Google account:

       1. On the **Connect GCP to Pinecone** page, select the Pinecone organization that you want to use Google Cloud Marketplace.

          <Note>If you see a message saying that the subscription is still in process, wait a few minutes, refresh the page, and proceed only when the message has disappeared.</Note>
       2. On the **Confirm GCP marketplace connection** modal, click **Connect**. This takes you to your organization in the Pinecone console.

          Going forward, your usage of Pinecone will be billed through the Google Cloud Marketplace.

    3. Cancel your subscription in your previous marketplace:

       * For AWS:
         1. In the AWS Marketplace, go to the [Manage subscriptions](https://console.aws.amazon.com/marketplace) page in the AWS Marketplace.
         2. [Cancel the subscription](https://docs.aws.amazon.com/marketplace/latest/buyerguide/cancel-subscription.html#cancel-saas-subscription) to Pinecone.

       * For Microsoft:
         1. Go to [Azure SaaS Resource Management](https://portal.azure.com/#blade/HubsExtension/BrowseResourceBlade/resourceType/Microsoft.SaaS%2Fresources).
         2. Select your subscription to Pinecone.
         3. Click **Cancel subscription**.
         4. Confirm the cancellation.
  </Tab>

  <Tab title="Any marketplace → AWS">
    To change to an AWS Marketplace billing account, do the following:

    1. Subscribe to Pinecone in the AWS Marketplace:

       1. In the AWS Marketplace, go to the [Pinecone listing](https://aws.amazon.com/marketplace/pp/prodview-xhgyscinlz4jk) in the AWS Marketplace.
       2. Click **View purchase options**.
       3. On the **Subscribe to Pinecone Vector Database** page, review the offer and then click **Subscribe**.

          <Note>The billing unit listed does not reflect the actual cost or metering of costs for Pinecone. See the [Pinecone Pricing page](https://www.pinecone.io/pricing/) for accurate details.</Note>
       4. You'll see a message stating that your subscription is in process. Click **Set up your account**. This takes you to an AWS-specific Pinecone login page.
       5. Log in to your Pinecone account. Use the same authentication method as your existing Pinecone organization.

    2. Connect your existing org to your AWS account:

       1. On the **Connect AWS to Pinecone** page, select the Pinecone organization that you want to change to AWS Marketplace.

          <Note>If you see a message saying that the subscription is still in process, wait a few minutes, refresh the page, and proceed only when the message has disappeared.</Note>
       2. On the **Confirm AWS marketplace connection** modal, click **Connect**. This takes you to your organization in the Pinecone console.

          Going forward, your usage of Pinecone will be billed through the AWS Marketplace.

    3. Cancel your subscription in your previous marketplace:

       * For Google Cloud Marketplace:
         1. Go to the [Orders](https://console.cloud.google.com/marketplace/orders) page.
         2. [Cancel the order](https://cloud.google.com/marketplace/docs/manage-billing#saas-products) for Pinecone.

       * For Microsoft Marketplace:
         1. Go to [Azure SaaS Resource Management](https://portal.azure.com/#blade/HubsExtension/BrowseResourceBlade/resourceType/Microsoft.SaaS%2Fresources).
         2. Select your subscription to Pinecone.
         3. Click **Cancel subscription**.
         4. Confirm the cancellation.
  </Tab>

  <Tab title="Any marketplace → Microsoft">
    To change to a Microsoft Marketplace billing account, do the following:

    1. Subscribe to Pinecone in the Microsoft Marketplace:

       1. In the Microsoft Marketplace, go to the [Pinecone listing](https://marketplace.microsoft.com/product/saas/pineconesystemsinc1688761585469.pineconesaas).
       2. Click **Get it now**.
       3. Select the **Pinecone - Pay As You Go** plan.
       4. Click **Subscribe**.
       5. On the **Subscribe to Pinecone** page, select the required details and click **Review + subscribe**.

          <Note>The billing unit listed does not reflect the actual cost or metering of costs for Pinecone. See the [Pinecone Pricing page](https://www.pinecone.io/pricing/) for accurate details.</Note>
       6. Click **Subscribe**.
       7. After the subscription is approved, click **Configure account now**. This redirects you to an Microsoft-specific Pinecone login page.
       8. Log in to your Pinecone account. Use the same authentication method as your existing Pinecone organization.

    2. Connect your existing org to your Microsoft account:

       1. On the **Connect Azure to Pinecone** page, select the Pinecone organization that you want to change to Microsoft Marketplace.

          <Note>If you see a message saying that the subscription is still in process, wait a few minutes, refresh the page, and proceed only when the message has disappeared.</Note>
       2. On the **Confirm Azure marketplace connection** modal, click **Connect**. This takes you to your organization in the Pinecone console.

          Going forward, your usage of Pinecone will be billed through the Microsoft Marketplace.

    3. Cancel your subscription in your previous marketplace:

       * For Google Cloud Marketplace:
         1. Go to the [Orders](https://console.cloud.google.com/marketplace/orders) page.
         2. [Cancel the order](https://cloud.google.com/marketplace/docs/manage-billing#saas-products) for Pinecone.

       * For AWS Marketplace:
         1. Go to the [Manage subscriptions](https://console.aws.amazon.com/marketplace) page in the AWS Marketplace.
         2. [Cancel the subscription](https://docs.aws.amazon.com/marketplace/latest/buyerguide/cancel-subscription.html#cancel-saas-subscription) to Pinecone.
  </Tab>
</Tabs>

## Credit card → credit card

To update your credit card information in the Pinecone console, do the following:

1. Go to [**Settings > Billing > Overview**](https://app.pinecone.io/organizations/-/settings/billing).
2. In the **Billing Contact** section, click **Edit**.
3. Enter your new credit card information.
4. Click **Update**.


# Configure audit logs
Source: https://docs.pinecone.io/guides/assistant/admin/configure-audit-logs

Set up Pinecone audit logs streamed to an Amazon S3 bucket to track user, service account, and API actions across the control plane.

This page describes how to configure audit logs in Pinecone. Audit logs provide a detailed record of user, service account, and API actions that occur on the management and [control plane](/guides/get-started/database-architecture#control-plane) within Pinecone. Pinecone supports Amazon S3 as a destination for audit logs.

<Note>
  To enable and manage audit logs, you must be an [organization owner](/guides/assistant/admin/organizations-overview#organization-roles). This feature is available only on [Enterprise plans](https://www.pinecone.io/pricing/) or with the HIPAA add-on.
</Note>

## Enable audit logs

Before you can enable audit logs, you need to create an IAM policy and role in Amazon S3. To start, ensure you have the following:

* A [Pinecone account](https://app.pinecone.io/).
* An [Amazon S3 bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/creating-buckets.html).

### 1. Create an IAM policy

In the [AWS IAM console](https://console.aws.amazon.com/iam/home):

1. In the navigation pane, click **Policies**.
2. Click **Create policy**.
3. In **Select a service** section, select **S3**.
4. Select the following actions to allow:
   * `ListBucket`: Permission to list some or all of the objects in an S3 bucket.
   * `PutObject`: Permission to add an object to an S3 bucket.
5. In the **Resources** section, select **Specific**.
6. For the **bucket**, specify the ARN of the bucket you created. For example: `arn:aws:s3:::example-bucket-name`
7. For the **object**, specify an object ARN as the target resource. For example: `arn:aws:s3:::example-bucket-name/*`
8. Click **Next**.
9. Specify the name of your policy. For example:  "Pinecone-S3-Access".
10. Click **Create policy**.

### 2. Set up access using an IAM role

In the [AWS IAM console](https://console.aws.amazon.com/iam/home):

1. In the navigation pane, click **Roles**.

2. Click **Create role**.

3. In the **Trusted entity type** section, select **AWS account**.

4. Select **Another AWS account**.

5. Enter the Pinecone AWS VPC account ID: `713131977538`

6. Click **Next**.

7. Select the policy you created.

8. Click **Next**.

9. Specify the role name. For example: "Pinecone".

10. Click **Create role**.

11. Click the role you created.

12. On the **Summary** page for the role, find the **ARN**.

    For example: `arn:aws:iam::123456789012:role/PineconeAccess`

13. Copy the **ARN**.

    You will need to enter the ARN into Pinecone later.

### 3. Connect Pinecone to Amazon S3

1. Go to [**Settings > Audit logs**](https://app.pinecone.io/organizations/-/settings/logging) in the Pinecone console.
2. Enter the **Role ARN** of the IAM role you created.
3. Enter the name of the Amazon S3 bucket you created.
4. Click **Enable audit logging**.

Once you enable audit logs, Pinecone will start writing logs to the S3 bucket. In your bucket, you will also see a file named `audit-log-access-test`, which is a test file that Pinecone writes to verify that it has the necessary permissions to write logs to the bucket.

## View audit logs

Logs are written to the S3 bucket approximately every 30 minutes. Each log batch will be saved into its own file as a JSON blob, keyed by the time of the log to be written. Only logs since the integration was created and enabled will be saved.

For more information about the log schema and captured events, see [Security overview - Audit logs](/guides/assistant/admin/security-overview#audit-logs).

## Edit audit log integration details

You can edit the details of the audit log integration in the Pinecone console:

1. Go to [**Settings > Audit logs**](https://app.pinecone.io/organizations/-/settings/logging).
2. Enter the new **Role ARN** or **AWS Bucket**.
3. Click **Update settings**.

## Disable audit logs

If you disable audit logs, logs not yet saved will be lost. You can disable audit logs in the Pinecone console:

1. Go to [**Settings > Audit logs**](https://app.pinecone.io/organizations/-/settings/logging).
2. Click the toggle next to **Audit logs are active**.
3. Click **Confirm**.

## Remove audit log integration

If you remove the audit log integration, logs not yet saved will be lost. You can remove the audit log integration in the Pinecone console:

1. Go to [**Settings > Audit logs**](https://app.pinecone.io/organizations/-/settings/logging).
2. At the top of the page, click the **ellipsis (...) menu > Remove integration**.
3. Click **Remove integration**.


# Configure SSO with Okta
Source: https://docs.pinecone.io/guides/assistant/admin/configure-sso-with-okta

Integrate Okta with Pinecone to enable single sign-on, configure SAML settings, and manage secure user authentication for your organization.

This page describes how to set up Pinecone with Okta as the single sign-on (SSO) provider. These instructions can be adapted for any provider with SAML 2.0 support.

<Note>SSO is available on Standard and Enterprise plans.</Note>

## Before you begin

This page assumes you have the following:

* Access to your organization's [Pinecone console](https://login.pinecone.io) as an [organization owner](/guides/organizations/understanding-organizations#organization-roles).
* Access to your organization's [Okta Admin console](https://login.okta.com/).

## 1. Start SSO setup in Pinecone

First, start setting up SSO in Pinecone. In this step, you'll capture a couple values necessary for configuring Okta in [Step 2](#2-create-an-app-integration-in-okta).

1. In the Pinecone console, go to [**Settings > Access > Identity provider**](https://app.pinecone.io/organizations/-/settings/access/identity-provider).
2. In the **Single sign-on** section, click **Enable SSO**.
3. In the **Setup SSO** dialog, copy the **Entity ID** and the **Assertion Consumer Service (ACS) URL**. You'll need these values in [Step 2](#2-create-an-app-integration-in-okta).
4. Click **Next**.

Keep this window or browser tab open. You'll come back to it in [Step 4](#4-complete-sso-setup-in-pinecone).

## 2. Create an app integration in Okta

In [Okta](https://login.okta.com/), follow these steps to create and configure a Pinecone app integration:

1. If you're not already on the Okta Admin console, navigate there by clicking the **Admin** button.

2. Navigate to **Applications > Applications**.

3. Click **Create App Integration**.

4. Select **SAML 2.0**.

5. Click **Next**.

6. Enter the **General Settings**:

   * **App name**: `Pinecone`
   * **App logo**: (optional)
   * **App visibility**: Set according to your organization's needs.

7. Click **Next**.

8. For **SAML Settings**, enter values you copied in [Step 1](#1-start-sso-setup-in-pinecone):

   * **Single sign-on URL**: Your **Assertion Consumer Service (ACS) URL**
   * **Audience URI (SP Entity ID)**: Your **Entity ID**
   * **Name ID format**: `EmailAddress`
   * **Application username**: `Okta username`
   * **Update application username on**: `Create and update`

9. In the **Attribute Statements (SAML)** section, create the following attribute:

   * **Name**: `email`
   * **Value**: `user.email`

   <Note>
     In newer versions of Okta, attribute statements are configured on the app's **Sign On** tab after the app is created, rather than in the app creation wizard. If you don't see the **Attribute Statements (SAML)** section here, finish creating the app, then add the attribute from **Applications > Pinecone > Sign On**, expanding **Show legacy configuration** if needed.
   </Note>

10. Click **Next**.

11. Click **Finish**.

## 3. Get the sign on URL and certificate from Okta

Next, in Okta, get the URL and certificate for the Pinecone application you just created. You'll use these in [Step 4](#4-complete-sso-setup-in-pinecone).

1. In the Okta Admin console, navigate to **Applications > Pinecone > Sign On**. If you're continuing from the previous step, you should already be on the right page.
2. In the **SAML 2.0** section, expand **More details**.
3. Copy the **Sign on URL**.
4. Download the **Signing Certificate**.

   <Warning>
     Download the certificate, don't copy it. The downloaded version contains necessary `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----` lines.
   </Warning>

## 4. Complete SSO setup in Pinecone

In the browser tab or window you kept open in [Step 1](#1-start-sso-setup-in-pinecone), complete the SSO setup in Pinecone:

1. In the **SSO Setup** window, enter the following values:

   * **Login URL**: The URL copied in [Step 3](#3-get-the-sign-on-url-and-certificate-from-okta).
   * **Email domain**: Your company's email domain. To target multiple domains, enter each domain separated by a comma.
   * **Certificate**: The contents of the certificate file you copied in [Step 3](#3-get-the-sign-on-url-and-certificate-from-okta).

     <Warning>
       When pasting the certificate, be sure to include the `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----` lines.
     </Warning>

2. Choose whether or not to **Enforce SSO for all users**.

   * If enabled, all members of your organization must use SSO to log in to Pinecone.
   * If disabled, members can choose to log in with SSO or with their Pinecone credentials.

3. Click **Next**.

4. Select a **Default role** for all users who log in with SSO. You can change user roles later.

   <Note>
     The **Default role** does not apply if you enable [SAML role management](/guides/production/configure-single-sign-on/okta-role-management). In that mode, every user's organization and project roles come entirely from your identity provider's SAML attributes.
   </Note>

   <Warning>
     When users first log in via SSO, they receive the default SSO role regardless of their previous role. Subsequent SSO logins do not change the role. If the default is **Member** or **Manager**, existing owners will lose owner access on their first SSO login.

     To prevent losing access to organization management features:

     * **Sole owner**: Temporarily set the default to **Owner**, log in via SSO to retain owner access, then change the default back to **Member**. After changing it back, check your organization's user list to verify no one else logged in via SSO while the default was **Owner**—if they did, adjust their roles accordingly.
     * **Multiple owners**: Keep at least one owner signed in via email while others log in via SSO. That owner can restore roles as needed, then log in via SSO last.

     If all owners lose access, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).
   </Warning>

Okta is now ready to be used for single sign-on. Follow the [Okta docs](https://help.okta.com/en-us/content/topics/users-groups-profiles/usgp-main.htm) to learn how to add users and groups.

## Manage roles automatically

Optionally, you can have Pinecone assign organization and project roles automatically from your identity provider on each login, instead of managing them manually. For more information, see [Manage roles with Okta](/guides/production/configure-single-sign-on/okta-role-management).


# Downgrade your plan
Source: https://docs.pinecone.io/guides/assistant/admin/downgrade-billing-plan

Downgrade your Pinecone subscription from a paid tier back to the free Starter plan, including steps to review usage limits before switching.

<Note>
  To change your billing plan, you must be an [organization owner or billing admin](/guides/organizations/understanding-organizations#organization-roles).
</Note>

<Tip>
  If you are on the Standard plan with credit/debit card billing and want to reduce spend without returning to the free Starter plan, consider [switching to the Builder plan](#switch-from-standard-to-builder) for a flat \$20/month.
</Tip>

## Requirements

Before you can downgrade, your organization must be under the [Starter plan quotas](/reference/api/database-limits):

* No more than 5 indexes, all serverless and in the `us-east-1` region of AWS
  * If you have serverless indexes in a region other than `us-east-1`, [create a new serverless index](/guides/index-data/create-an-index#create-a-serverless-index) in `us-east-1`, [re-upsert your data](/guides/index-data/upsert-data) into the new index, and [delete the old index](/guides/manage-data/manage-indexes#delete-an-index).
  * If you have more than 5 serverless indexes, [delete indexes](/guides/manage-data/manage-indexes#delete-an-index) until you have 5 or fewer.
  * If you have pod-based indexes, [delete them](/guides/manage-data/manage-indexes#delete-an-index).
* No more than 1 project
  * If you have more than 1 project, [delete all but 1 project](/guides/projects/manage-projects#delete-a-project).
  * Before you can delete a project, you must [delete all indexes](/guides/manage-data/manage-indexes#delete-an-index) and [delete all collections](/guides/manage-data/back-up-an-index#delete-a-collection) in the project.
* No more than 2 GB of data across all of your serverless indexes
  * If you are storing more than 2 GB of data, [delete records](/guides/manage-data/delete-data) until you're storing less than 2 GB.
* No more than 100 namespaces per serverless index
  * If any serverless index has more than 100 namespaces, [delete namespaces](/guides/manage-data/delete-data#delete-all-records-from-a-namespace) until it has 100 or fewer remaining.
* No more than 3 [assistants](/guides/assistant/overview)
  * If you have more than 3 assistants, [delete assistants](/guides/assistant/manage-assistants#delete-an-assistant) until you have 3 or fewer.
* Within the Starter plan's monthly [ingestion](/guides/assistant/pricing-and-limits#ingestion) and token limits
  * Your usage must fit within the Starter plan limits for [ingestion units](/guides/assistant/pricing-and-limits#ingestion), chat tokens, context tokens, and storage. Reduce files or usage until you are within those limits.
* No more than 1 GB of assistant storage
  * If you have more than 1 GB of assistant storage, [delete files](https://docs.pinecone.io/guides/assistant/manage-files#delete-a-file) until you're storing less than 1 GB.
* No more than 2 users
* No collections or backups (these are automatically deleted as part of the downgrade process)

<Note>
  You do not need to bring [Assistant usage](/guides/assistant/pricing-and-limits) (ingestion, tokens, and so on) under Starter caps before downgrading. If you exceed Starter limits after downgrading, new requests may be blocked until usage is within limits.
</Note>

<Note>
  **Switching from Standard to Builder instead of Starter?** Your organization must be under the [Builder plan quotas](/reference/api/database-limits), backups must be deleted, and any features not available on Builder—such as bulk import, pod-based indexes, storage integrations, RBAC, and SSO—must be removed or stopped.
</Note>

## Downgrade to the Starter plan

The downgrade process is different depending on how you are paying for Pinecone.

<Warning>
  It is important to start the downgrade process in the Pinecone console, as described below. When you do so, Pinecone checks that you are under the [Starter plan quotas](#requirements) before allowing you to downgrade. In contrast, if you start the downgrade process in one of the cloud marketplaces, Pinecone cannot check that you are under these quotas before allowing you to downgrade. If you are over the quotas, Pinecone will deactivate your account, and you will need to [contact support](https://www.pinecone.io/contact/support/).
</Warning>

<Tabs>
  <Tab title="Credit card">
    If you are paying with a credit card, downgrade as follows:

    1. In the Pinecone console, go to [**Settings > Billing > Plans**](https://app.pinecone.io/organizations/-/settings/billing/plans).
    2. Click **Downgrade** in the **Starter** plan section.

    Your billing will end immediately. However, you will receive a final invoice for any charges accrued in the current month.
  </Tab>

  <Tab title="Google Cloud Marketplace">
    If you are paying through the Google Cloud Marketplace, downgrade as follows:

    1. In the Pinecone console, go to [**Settings > Billing > Plans**](https://app.pinecone.io/organizations/-/settings/billing/plans).
    2. In the **Starter** section, click **Downgrade**.
    3. Click **Confirm downgrade**.
    4. On the **Continue your downgrade on the GCP marketplace** modal, click **Continue to marketplace**. This takes you to your orders page in Google Cloud Marketplace.
    5. [Cancel the order](https://cloud.google.com/marketplace/docs/manage-billing#saas-products) for your Pinecone subscription.

       <Tip>
         If you don't see the order, check that the correct billing account is selected.
       </Tip>

    Your billing will end immediately. However, you will receive a final invoice for any charges accrued in the current month.
  </Tab>

  <Tab title="AWS Marketplace">
    If you are paying through the AWS Marketplace, downgrade as follows:

    1. In the Pinecone console, go to [**Settings > Billing > Plans**](https://app.pinecone.io/organizations/-/settings/billing/plans).
    2. In the **Starter** section, click **Downgrade**.
    3. Click **Confirm downgrade**.
    4. On the **Continue your downgrade on the AWS marketplace** modal, click **Continue to marketplace**. This takes you to the [Manage subscriptions](https://console.aws.amazon.com/marketplace) page in the AWS Marketplace.
    5. [Cancel the subscription](https://docs.aws.amazon.com/marketplace/latest/buyerguide/cancel-subscription.html#cancel-saas-subscription) to Pinecone.

    Your billing will end immediately. However, you will receive a final invoice for any charges accrued in the current month.
  </Tab>

  <Tab title="Microsoft Marketplace">
    If you are paying through the Microsoft Marketplace, downgrade as follows:

    1. In the Pinecone console, go to [**Settings > Billing > Plans**](https://app.pinecone.io/organizations/-/settings/billing/plans).
    2. In the **Starter** section, click **Downgrade**.
    3. Click **Confirm downgrade**.
    4. On the **Continue your downgrade on Microsoft marketplace** modal, click **Continue to marketplace**.
    5. On the **SaaS** page, click your subscription to Pinecone.
    6. Click **Cancel subscription**.
    7. Confirm the cancellation.

    Your billing will end immediately. However, you will receive a final invoice for any charges accrued in the current month.
  </Tab>
</Tabs>

## Switch from Standard to Builder

If you are on the **Standard plan** with credit/debit card billing and would like to switch to the [Builder plan](/reference/api/database-limits) (flat \$20/month), do the following:

1. Bring your organization under the [Builder plan quotas](/reference/api/database-limits). In particular, you must be within the Builder plan limits for projects, indexes, namespaces, storage, users, and monthly usage units.
2. In the Pinecone console, go to [**Settings > Billing > Plans**](https://app.pinecone.io/organizations/-/settings/billing/plans).
3. Click **Switch to Builder** in the **Builder** plan section.
4. Confirm the change.

After switching, overages are no longer billed—requests that exceed Builder quotas are blocked instead. If you need more capacity, [upgrade back to Standard or Enterprise](/guides/organizations/manage-billing/upgrade-billing-plan) at any time.

<Note>
  The [Builder plan](https://www.pinecone.io/pricing/) is available with credit/debit card billing only and is not supported through cloud marketplaces.
</Note>

If you pay through a cloud marketplace, you cannot switch to the Builder plan at this time. [Contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) to be notified when this migration becomes available.


# Download a usage report
Source: https://docs.pinecone.io/guides/assistant/admin/download-usage-report

Export a detailed Pinecone usage and cost report for your organization to analyze index consumption, credits, and monthly billing charges.

<Note>
  To view usage and costs across your Pinecone organization, you must be an [organization owner or billing admin](/guides/organizations/understanding-organizations#organization-roles). Also, this feature is available only to organizations on the Standard or Enterprise plans.
</Note>

The **Usage** dashboard in the Pinecone console gives you a detailed report of usage and costs across your organization, broken down by each billable SKU or aggregated by project or service. You can view the report in the console or download it as a CSV file for more detailed analysis.

1. Go to [**Settings > Usage**](https://app.pinecone.io/organizations/-/settings/usage) in the Pinecone console.
2. Select the time range to report on. This defaults to the last 30 days.
3. Select the scope for your report:
   * **SKU:** The usage and cost for each billable SKU, for example, read units per cloud region, storage size per cloud region, or tokens per embedding model.
   * **Project:** The aggregated cost for each project in your organization.
   * **Service:** The aggregated cost for each service your organization uses, for example, database (includes serverless back up and restore), assistants, inference (embedding and reranking), and collections.
4. Choose the specific SKUs, projects, or services you want to report on. This defaults to all.
5. To download the report as a CSV file, click **Download**.

   <Tip>
     The CSV download provides more granular detail than the console view, including breakdowns by individual index as well as project and index tags.
   </Tip>

Dates are shown in UTC to match billing invoices. Cost data is delayed up to three days from the actual usage date.


# Manage roles and access
Source: https://docs.pinecone.io/guides/assistant/admin/manage-rbac

Assign and manage roles for users, service accounts, and API keys using the Pinecone console or the Admin API.

Pinecone uses [role-based access controls (RBAC)](/guides/assistant/admin/security-overview#role-based-access-controls-rbac) to manage access to resources. Users, service accounts, and API keys are all *principals*, and a principal's access is determined by the *roles* assigned to it for a *resource* (an organization or a project).

This page shows how to assign and manage roles in the [Pinecone console](https://app.pinecone.io) and programmatically with the Admin API.

<Note>
  For the roles available at each scope and the permissions they grant, see [Organization roles](/guides/assistant/admin/organizations-overview#organization-roles) and [Project roles](/guides/assistant/admin/projects-overview#project-roles).
</Note>

## Common role assignments

A user must have an organization role to belong to the organization, and gains access to a project through one or more project roles. A principal's effective permissions are the union of all the roles it holds, so you can combine roles to grant exactly the access a user needs.

The following table maps common scenarios to the roles to assign:

| Scenario                                                           | Organization role | Project role(s)                                                                       |
| :----------------------------------------------------------------- | :---------------- | :------------------------------------------------------------------------------------ |
| Administer the organization and every project                      | `OrgOwner`        | None (inherits owner access to all projects)                                          |
| Create and manage projects, but not billing or members             | `OrgManager`      | Assign per project as needed                                                          |
| Manage billing, subscriptions, and usage                           | `OrgBillingAdmin` | None                                                                                  |
| Lead a single project, including its members and API keys          | `OrgMember`       | `ProjectOwner`                                                                        |
| Build and query in a project, without managing members or API keys | `OrgMember`       | `ProjectManager`                                                                      |
| Read and write index data only                                     | `OrgMember`       | `ProjectMember` and `DataPlaneEditor`                                                 |
| Read-only access to a project's resources and data                 | `OrgMember`       | `ProjectMember`, `ControlPlaneViewer`, and `DataPlaneViewer`                          |
| Work across two projects at different access levels                | `OrgMember`       | `ProjectManager` on one project and `ProjectMember` with `DataPlaneViewer` on another |

<Note>
  Assigning an organization role adds the user to the organization; assigning a project role grants access to that specific project. To assign these roles in the console, see [Manage organization members](/guides/assistant/admin/manage-organization-members) and [Manage project members](/guides/assistant/admin/manage-project-members).
</Note>

### Invite a developer to a project

Invite a user as an organization member and grant them the `ProjectManager` role so they can build and query in a single project without managing its members or API keys.

In the console, add the user from [Manage project members](/guides/assistant/admin/manage-project-members) and select the **Project manager** role. With the Admin API, include both roles in the `role_bindings` array when you invite the user:

```bash curl theme={null}
PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

curl "https://api.pinecone.io/admin/invites" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Pinecone-Api-Version: 2026-04" \
  -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
  -d '{
    "email": "developer@example.com",
    "role_bindings": [
      {
        "resource_type": "organization",
        "role": "OrgMember"
      },
      {
        "resource_type": "project",
        "resource_id": "a2f7dddb-1597-4eff-9f71-535fde243f58",
        "role": "ProjectManager"
      }
    ]
  }'
```

For more information, see [Assign roles when creating a principal](#assign-roles-when-creating-a-principal).

### Grant an existing user read-only data access

To give a user who is already in your organization read-only access to a project's data, assign the `ProjectMember` role for baseline project access and the `DataPlaneViewer` role for read-only data. Each role binding is a separate request.

First, add the user to the project with the `ProjectMember` role:

```bash curl theme={null}
PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

curl "https://api.pinecone.io/admin/role-bindings" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Pinecone-Api-Version: 2026-04" \
  -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
  -d '{
    "principal_type": "user",
    "principal_id": "c7b1f0a2-3d4e-5f6a-7b8c-9d0e1f2a3b4c",
    "resource_type": "project",
    "resource_id": "a2f7dddb-1597-4eff-9f71-535fde243f58",
    "role": "ProjectMember"
  }'
```

Then, grant read-only data access with the `DataPlaneViewer` role:

```bash curl theme={null}
PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

curl "https://api.pinecone.io/admin/role-bindings" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Pinecone-Api-Version: 2026-04" \
  -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
  -d '{
    "principal_type": "user",
    "principal_id": "c7b1f0a2-3d4e-5f6a-7b8c-9d0e1f2a3b4c",
    "resource_type": "project",
    "resource_id": "a2f7dddb-1597-4eff-9f71-535fde243f58",
    "role": "DataPlaneViewer"
  }'
```

### Extend a user's access with an additional role

Because effective permissions are the union of all roles, you can broaden access by adding another role rather than replacing the existing one. The user from the previous example holds `ProjectMember` and `DataPlaneViewer`; add `ControlPlaneViewer` to also allow read-only access to the project's indexes, assistants, backups, and collections:

```bash curl theme={null}
PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

curl "https://api.pinecone.io/admin/role-bindings" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Pinecone-Api-Version: 2026-04" \
  -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
  -d '{
    "principal_type": "user",
    "principal_id": "c7b1f0a2-3d4e-5f6a-7b8c-9d0e1f2a3b4c",
    "resource_type": "project",
    "resource_id": "a2f7dddb-1597-4eff-9f71-535fde243f58",
    "role": "ControlPlaneViewer"
  }'
```

The user now holds `ProjectMember`, `DataPlaneViewer`, and `ControlPlaneViewer` on the project, giving read-only access to all of its resources and data. For more information, see [Create a role binding](#create-a-role-binding).

## Manage roles in the console

You can assign and change roles when you manage principals in the console:

* [Manage organization members](/guides/assistant/admin/manage-organization-members)
* [Manage project members](/guides/assistant/admin/manage-project-members)
* [Manage organization service accounts](/guides/assistant/admin/manage-organization-service-accounts) and [project service accounts](/guides/assistant/admin/manage-project-service-accounts)
* [Manage API keys](/guides/assistant/admin/manage-api-keys)

## Manage roles with the Admin API

The Admin API represents each role assignment as a *role binding* that grants one role to one principal for one resource scope. You can assign roles when you create a principal, or manage role bindings directly after creation.

<Note>
  An [access token](/guides/assistant/admin/manage-organization-service-accounts#retrieve-an-access-token) must be provided to authenticate with the Admin API.
</Note>

### Assign roles when creating a principal

When you invite a user or create a service account, grant roles with the `role_bindings` field. Set `resource_type` to `organization` or `project`; for `project` scope, include the project's `resource_id`.

Invite a user as an organization member with a project role:

```bash curl theme={null}
PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

curl "https://api.pinecone.io/admin/invites" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Pinecone-Api-Version: 2026-04" \
  -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
  -d '{
    "email": "newhire@example.com",
    "role_bindings": [
      {
        "resource_type": "organization",
        "role": "OrgMember"
      },
      {
        "resource_type": "project",
        "resource_id": "a2f7dddb-1597-4eff-9f71-535fde243f58",
        "role": "ProjectMember"
      }
    ]
  }'
```

Create a service account with an access role:

```bash curl theme={null}
PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

curl "https://api.pinecone.io/admin/service-accounts" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Pinecone-Api-Version: 2026-04" \
  -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
  -d '{
    "name": "ci-prod",
    "role_bindings": [
      {
        "resource_type": "project",
        "resource_id": "a2f7dddb-1597-4eff-9f71-535fde243f58",
        "role": "DataPlaneEditor"
      }
    ]
  }'
```

For API keys, assign [project roles](/guides/assistant/admin/projects-overview#project-roles) with the `roles` field instead. For more information, see [Manage API keys](/guides/assistant/admin/manage-api-keys).

### Create a role binding

To grant a role to an existing principal, create a role binding:

```bash curl theme={null}
PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

curl "https://api.pinecone.io/admin/role-bindings" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Pinecone-Api-Version: 2026-04" \
  -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
  -d '{
    "principal_type": "service_account",
    "principal_id": "f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
    "resource_type": "project",
    "resource_id": "a2f7dddb-1597-4eff-9f71-535fde243f58",
    "role": "DataPlaneEditor"
  }'
```

For more information, see [Create a role binding](/reference/api/2026-04/admin/create_role_binding).

### List role bindings

Role bindings are not included in the responses for users, invites, or service accounts. To list the roles assigned to a principal, filter by `principal_type` and `principal_id`:

```bash curl theme={null}
PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

curl "https://api.pinecone.io/admin/role-bindings?principal_type=service_account&principal_id=f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c" \
  -H "Accept: application/json" \
  -H "X-Pinecone-Api-Version: 2026-04" \
  -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN"
```

For more information, see [List role bindings](/reference/api/2026-04/admin/list_role_bindings) and [Fetch a role binding](/reference/api/2026-04/admin/fetch_role_binding).

### Delete a role binding

To revoke a role, delete its role binding:

```bash curl theme={null}
PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

curl -X DELETE "https://api.pinecone.io/admin/role-bindings/9a8e3528-b9c0-4358-84ce-84c28e91b566" \
  -H "Accept: application/json" \
  -H "X-Pinecone-Api-Version: 2026-04" \
  -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN"
```

<Warning>
  You cannot delete the last `OrgOwner` role binding for an organization. An organization must always have at least one owner.
</Warning>

For more information, see [Delete a role binding](/reference/api/2026-04/admin/delete_role_binding).


# Organizations overview
Source: https://docs.pinecone.io/guides/assistant/admin/organizations-overview

Learn how Pinecone organizations group projects under shared billing, and how organization owners, members, and roles control access and permissions.

A Pinecone organization is a set of [projects](/guides/assistant/admin/projects-overview) that use the same billing. Organizations allow one or more users to control billing and project permissions for all of the projects belonging to the organization. Each project belongs to an organization.

<Note>
  While an email address can be associated with multiple organizations, it cannot be used to create more than one organization. For information about managing organization members, see [Manage organization members](/guides/assistant/admin/manage-organization-members).
</Note>

## Projects in an organization

Each organization contains one or more projects that share the same organization owners and billing settings. Each project belongs to exactly one organization. If you need to move a project from one organization to another, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket).

## Billing settings

All of the projects in an organization share the same billing method and settings. The billing settings for the organization are controlled by the organization owners.

Organization owners can update the billing contact information, update the payment method, and view and download invoices using the [Pinecone console](https://app.pinecone.io/organizations/-/settings/billing).

## Organization roles

Organization owners can manage access to their organizations and projects by assigning roles to organization members and service accounts. A role determines the permissions that a [principal](/guides/assistant/admin/security-overview#role-based-access-controls-rbac) (a user, service account, or API key) has within Pinecone. The organization roles are as follows:

* **Organization owner** (`OrgOwner`): Full control over the organization, including billing, members, service accounts, security, and every project. Inherits [owner access](/guides/assistant/admin/projects-overview#project-roles) to all projects in the organization.

* **Organization manager** (`OrgManager`): Can view organization details and create projects. Organization managers cannot manage billing, members, service accounts, or organization settings.

* **Organization member** (`OrgMember`): Can view organization details and access the projects they are added to. Organization members cannot create projects or manage organization settings. To grant project access, add the member to one or more projects and assign a [project role](/guides/assistant/admin/projects-overview#project-roles); see [Manage project members](/guides/assistant/admin/manage-project-members).

* **Billing admin** (`OrgBillingAdmin`): Can view organization details and manage billing, subscriptions, and usage. Billing admins cannot manage members or organization settings, and they cannot manage projects unless they are also [project owners](/guides/assistant/admin/projects-overview#project-roles).

The following table summarizes the permissions for each organization role:

| Permission                             | Owner | Manager | Member | Billing admin |
| -------------------------------------- | :---: | :-----: | :----: | :-----------: |
| View account details                   |   ✓   |    ✓    |    ✓   |       ✓       |
| Create projects                        |   ✓   |    ✓    |        |               |
| View billing and usage details         |   ✓   |         |        |       ✓       |
| Manage billing details                 |   ✓   |         |        |       ✓       |
| Invite and remove organization members |   ✓   |         |        |               |
| Update organization member roles       |   ✓   |         |        |               |
| Manage service accounts                |   ✓   |         |        |               |
| Configure single sign-on (SSO)         |   ✓   |         |        |               |
| Configure audit logs                   |   ✓   |         |        |               |
| Update organization name               |   ✓   |         |        |               |
| Delete the organization                |   ✓   |         |        |               |

## Organization single sign-on (SSO)

SSO allows organizations to manage their teams' access to Pinecone through their identity management solution. Once your integration is configured, you can specify a default role for teammates when they sign up.

<Note>For organizations that use SSO for authentication, console sessions are re-authenticated at least every 24 hours.</Note>

For more information, see [Configure single sign-on](/guides/assistant/admin/configure-sso-with-okta).

<Note>SSO is available on Standard and Enterprise plans.</Note>

## Service accounts

<Note>
  This feature is in [public preview](/release-notes/feature-availability) and available only on [Enterprise plans](https://www.pinecone.io/pricing/).
</Note>

[Service accounts](/guides/assistant/admin/manage-organization-service-accounts) enable programmatic access to Pinecone's Admin API, which can be used to create and manage projects and API keys.

Use service accounts to automate infrastructure management and integrate Pinecone into your deployment workflows, rather than through manual actions in the Pinecone console. Service accounts use the [organization roles](/guides/assistant/admin/organizations-overview#organization-roles) and [project role](/guides/assistant/admin/projects-overview#project-roles) for permissioning, and provide a secure and auditable way to handle programmatic access.

## See also

* [Manage organization members](/guides/assistant/admin/manage-organization-members)
* [Manage project members](/guides/assistant/admin/manage-project-members)
* [Project overview](/guides/assistant/admin/projects-overview)


# Security overview
Source: https://docs.pinecone.io/guides/assistant/admin/security-overview

Overview of Pinecone Assistant admin security features including API keys, single sign-on, service accounts, and audit logs across your organization.

This page describes Pinecone's security protocols, practices, and features.

## Access management

### API keys

Each Pinecone [project](/guides/assistant/admin/projects-overview) has one or more [API keys](/guides/assistant/admin/manage-api-keys). In order to make calls to the Pinecone API, a user must provide a valid API key for the relevant Pinecone project.

You can [manage API key permissions](/guides/assistant/admin/manage-api-keys) in the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/keys). For the roles you can assign to an API key and the operations each role covers, see [Project roles](/guides/assistant/admin/projects-overview#project-roles).

### Organization single sign-on (SSO)

SSO allows organizations to manage their teams' access to Pinecone through their identity management solution. Once your integration is configured, you can require that users from your domain sign in through SSO, and you can specify a default role for teammates when they sign up. SSO is available on Standard and Enterprise plans.

For more information, see [configure single sign on](/guides/assistant/admin/configure-sso-with-okta).

### Role-based access controls (RBAC)

Pinecone uses role-based access controls (RBAC) to manage access to resources.

Service accounts, API keys, and users are all *principals*. A principal's access is determined by the *roles* assigned to it. Roles are assigned to a principal for a *resource*, either a project or an organization. The roles available to be assigned depend on the type of principal and resource.

You can manage roles in the [Pinecone console](https://app.pinecone.io) or programmatically with the Admin API. For more information, see [Manage roles and access](/guides/assistant/admin/manage-rbac).

#### Service account roles

A service account can be assigned roles for the organization it belongs to, and any projects within that organization. For more information, see [Organization roles](/guides/assistant/admin/organizations-overview#organization-roles) and [Project roles](/guides/assistant/admin/projects-overview#project-roles).

#### API key roles

An API key can be assigned any [project role](/guides/assistant/admin/projects-overview#project-roles) except `ProjectOwner`, `ProjectManager`, and `ProjectMember`, and only for the project it belongs to. For more information, see [API keys](#api-keys).

#### User roles

A user can be assigned roles for each organization they belong to, and any projects within that organization. For more information, see [Organization roles](/guides/assistant/admin/organizations-overview#organization-roles) and [Project roles](/guides/assistant/admin/projects-overview#project-roles).

## Compliance

<Note>
  To learn more about data privacy and compliance at Pinecone, visit the [Pinecone Trust and Security Center](https://security.pinecone.io/).
</Note>

### Audit logs

<Note>
  To enable and manage audit logs, you must be an [organization owner](/guides/assistant/admin/organizations-overview#organization-roles). This feature is available only on [Enterprise plans](https://www.pinecone.io/pricing/).
</Note>

[Audit logs](/guides/assistant/admin/configure-audit-logs) provide a detailed record of user and API actions that occur within Pinecone.

Events are captured every 30 minutes and each log batch will be saved into its own file as a JSON blob, keyed by the time of the log to be written. Only logs since the integration was created and enabled will be saved.

Audit log events adhere to a standard JSON schema and include the following fields:

```jsonc JSON theme={null}
{
    "id": "00000000-0000-0000-0000-000000000000",
    "organization_id": "AA1bbbbCCdd2EEEe3FF",
    "organization_name": "example-org",
    "client": {
        "userAgent": "rawUserAgent"
    },
    "actor": {
        "principal_id": "00000000-0000-0000-0000-000000000000",
        "principal_name": "example@pinecone.io",
        "principal_type": "user", // user, api_key, service_account
        "display_name": "Example Person" // Only in case of user
    },
	"event": {
        "time": "2024-10-21T20:51:53.697Z",
        "action": "create",
        "resource_type": "index",
        "resource_id": "uuid",
        "resource_name": "docs-example",
        "outcome": {
            "result": "success",
            "reason": "", // Only displays for "result": "failure"
            "error_code": "", // Only displays for "result": "failure"
        },
        "parameters": { // Varies based on event
        }
	}
}
```

The following events are captured in the audit logs:

* [Organization events](#organization-events)
* [Project events](#project-events)
* [Index events](#index-events)
* [User and API key events](#user-and-api-key-events)
* [Security and governance events](#security-and-governance-events)

#### Organization events

| Action            | Query parameters                                                                                               |
| ----------------- | -------------------------------------------------------------------------------------------------------------- |
| Rename org        | `event.action: update`, `event.resource_type: organization`, `event.resource_id: NEW_ORG_NAME`                 |
| Delete org        | `event.action: delete`, `event.resource_type: organization`, `event.resource_id: DELETED_ORG_NAME`             |
| Create org member | `event.action: create`, `event.resource_type: user`, `event.resource_id: [ARRAY_OF_USER_EMAILS]`               |
| Update org member | `event.action: update`, `event.resource_type: user`, `event.resource_id: { user: USER_EMAIL, role: NEW_ROLE }` |
| Delete org member | `event.action: delete`, `event.resource_type: user`, `event.resource_id: USER_EMAIL`                           |

#### Project events

| Action                     | Query parameters                                                                                                   |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| Create project             | `event.action: create`, `event.resource_type: project`, `event.resouce_id: PROJ_NAME`                              |
| Update project             | `event.action: update`, `event.resource_type: project`, `event.resource_id: PROJECT_NAME`                          |
| Delete project             | `event.action: delete`, `event.resource_type: project`, `event.resource_id: PROJECT_NAME`                          |
| Invite project member      | `event.action: create`, `event.resource_type: user`, `event.resource_id: [ARRAY_OF_USER_EMAILS]`                   |
| Update project member role | `event.action: update`, `event.resource_type: user`, `event.resource_id: { user: USER_EMAIL, role: NEW_ROLE }`     |
| Delete project member      | `event.action: delete`, `event.resource_type: user`, `event.resource_id: { user: USER_EMAIL, project: PROJ_NAME }` |

#### Index events

| Action        | Query parameters                                                                        |
| ------------- | --------------------------------------------------------------------------------------- |
| Create index  | `event.action: create`, `event.resource_type: index`, `event.resouce_id: INDEX_NAME`    |
| Update index  | `event.action: update`, `event.resource_type: index`, `event.resource_id: INDEX_NAME`   |
| Delete index  | `event.action: delete`, `event.resource_type: index`, `event.resource_id: INDEX_NAME`   |
| Create backup | `event.action: create`, `event.resource_type: backup`, `event.resource_id: BACKUP_NAME` |
| Delete backup | `event.action: delete`, `event.resource_type: backup`, `event.resource_id: BACKUP_NAME` |

#### User and API key events

| Action         | Query parameters                                                                        |
| -------------- | --------------------------------------------------------------------------------------- |
| User login     | `event.action: login`, `event.resource_type: user`, `event.resouce_id: USERNAME`        |
| Create API key | `event.action: create`, `event.resource_type: api-key`, `event.resource_id: API_KEY_ID` |
| Delete API key | `event.action: delete`, `event.resource_type: api-key`, `event.resource_id: API_KEY_ID` |

#### Security and governance events

| Action                  | Query parameters                                                                                           |
| ----------------------- | ---------------------------------------------------------------------------------------------------------- |
| Create Private Endpoint | `event.action: create`, `event.resource_type: private-endpoints`, `event.resource_id: PRIVATE_ENDPOINT_ID` |
| Delete Private Endpoint | `event.action: delete`, `event.resource_type: private-endpoints`, `event.resource_id: PRIVATE_ENDPOINT_ID` |

## Data protection

### Encryption at rest

Pinecone encrypts stored data using the 256-bit Advanced Encryption Standard (AES-256) encryption algorithm.

### Encryption in transit

Pinecone uses standard protocols to encrypt user data in transit. Clients open HTTPS or gRPC connections to the Pinecone API; the Pinecone API gateway uses gRPC connections to user deployments in the cloud. These HTTPS and gRPC connections use the TLS 1.2 protocol with 256-bit Advanced Encryption Standard (AES-256) encryption.

<img alt="Diagram showing encryption protocols for user data in transit" />

Traffic is also encrypted in transit between the Pinecone backend and cloud infrastructure services, such as S3 and GCS. For more information, see [Google Cloud Platform](https://cloud.google.com/docs/security/encryption-in-transit) and [AWS security documentation](https://docs.aws.amazon.com/AmazonS3/userguide/UsingEncryption.html).

## Network security

### Proxies

The following Pinecone SDKs support the use of proxies:

* [Python SDK](/reference/sdks/python/overview#proxy-configuration)
* [Node.js SDK](/reference/sdks/node/overview#proxy-configuration)


# Upgrade your plan
Source: https://docs.pinecone.io/guides/assistant/admin/upgrade-billing-plan

Learn how Pinecone Assistant admins upgrade to a paid plan to unlock higher limits, more files, evaluations, and advanced access controls.

This page describes how to upgrade from the free Starter plan to the [Builder, Standard, or Enterprise plan](https://www.pinecone.io/pricing/), paying either with a credit/debit card or through a supported cloud marketplace.

<Note>
  To change your plan, you must be an [organization owner or billing admin](/guides/organizations/understanding-organizations#organization-roles).
</Note>

<Tip>
  To commit to annual spending, [contact Pinecone](https://www.pinecone.io/contact).
</Tip>

## Upgrade to the Builder plan

The Builder plan is a flat \$20/month plan with higher quotas than Starter and no usage overages. To upgrade from Starter to Builder:

1. In the Pinecone console, go to [Settings > Billing > Plans](https://app.pinecone.io/organizations/-/settings/billing/plans).
2. Click **Upgrade** in the **Builder** plan section.
3. Enter your credit/debit card information.
4. Click **Upgrade**.

After upgrading, your organization is immediately on the Builder plan with the higher [Builder plan quotas](/reference/api/database-limits). If you need additional capacity or features not included in Builder, you can [upgrade to Standard or Enterprise](#upgrade-to-the-standard-or-enterprise-plan) at any time.

<Note>
  The [Builder plan](https://www.pinecone.io/pricing/) is available with credit/debit card billing only and is not supported through cloud marketplaces.
</Note>

## Upgrade to the Standard or Enterprise plan

### Pay with a credit/debit card

To upgrade your plan to Standard or Enterprise and pay with a credit/debit card, do the following:

1. In the Pinecone console, go to [Settings > Billing > Plans](https://app.pinecone.io/organizations/-/settings/billing/plans).
2. Click **Upgrade** in the **Standard** or **Enterprise** plan section.
3. Click **Credit / Debit card**.
4. Enter your credit card information.
5. Click **Upgrade**.

After upgrading, you will immediately start paying for usage of your Pinecone indexes, including the serverless indexes that were free on the Starter plan. For more details about how costs are calculated, see [Understanding cost](/guides/manage-cost/understanding-cost).

### Pay through the Google Cloud Marketplace

To upgrade your plan to Standard or Enterprise and pay through the Google Cloud Marketplace, do the following:

1. In the Pinecone console, go to [Settings > Billing > Plans](https://app.pinecone.io/organizations/-/settings/billing/plans).
2. Click **Upgrade** in the **Standard** or **Enterprise** plan section.
3. Click **Billing through GCP**. This takes you to the [Pinecone listing](https://console.cloud.google.com/marketplace/product/pinecone-public/pinecone) in the Google Cloud Marketplace.
4. Click **Subscribe**.
5. On the **Order Summary** page, select a billing account, accept the terms and conditions, and click **Subscribe**.

   <Note>The billing unit listed does not reflect the actual cost or metering of costs for Pinecone. See the [Pinecone Pricing page](https://www.pinecone.io/pricing/) for accurate details.</Note>
6. On the **Your order request has been sent to Pinecone** modal, click **Sign up with Pinecone**. This takes you to a Google-specific Pinecone login page.
7. Log in to your Pinecone account. Use the same authentication method as your existing Pinecone organization.
8. Select an organization from the list. You can only connect to organizations that are on the [Starter plan](https://www.pinecone.io/pricing/). Alternatively, you can opt to create a new organization.
9. Click **Connect to Pinecone** and follow the prompts.

Once your organization is connected and upgraded, you will receive a confirmation message. You will then immediately start paying for usage of your Pinecone indexes, including the serverless indexes that were free on the Starter plan. For more details about how costs are calculated, see [Understanding cost](/guides/manage-cost/understanding-cost).

### Pay through the AWS Marketplace

To upgrade your plan to Standard or Enterprise and pay through the AWS Marketplace, do the following:

1. In the Pinecone console, go to [Settings > Billing > Plans](https://app.pinecone.io/organizations/-/settings/billing/plans).
2. Click **Upgrade** in the **Standard** or **Enterprise** plan section.
3. Click **Billing through AWS**. This takes you to the [Pinecone listing](https://aws.amazon.com/marketplace/pp/prodview-xhgyscinlz4jk) in the AWS Marketplace.
4. Click **View purchase options**.
5. On the **Subscribe to Pinecone Vector Database** page, review the offer and then click **Subscribe**.

   <Note>The billing unit listed does not reflect the actual cost or metering of costs for Pinecone. See the [Pinecone Pricing page](https://www.pinecone.io/pricing/) for accurate details.</Note>
6. You'll see a message stating that your subscription is in process. Click **Set up your account**. This takes you to an AWS-specific Pinecone login page.

   <Warning>
     If the [Pinecone subscription page](https://aws.amazon.com/marketplace/saas/ordering?productId=738798c3-eeca-494a-a2a9-161bee9450b2) shows a message stating, “You are currently subscribed to this offer,” contact your team members to request an invitation to the existing AWS-linked organization. The **Set up your account** button is clickable, but Pinecone does not create a new AWS-linked organization.
   </Warning>
7. Log in to your Pinecone account. Use the same authentication method as your existing Pinecone organization.
8. Select an organization from the list. You can only connect to organizations that are on the [Starter plan](https://www.pinecone.io/pricing/). Alternatively, you can opt to create a new organization.
9. Click **Connect to Pinecone** and follow the prompts.

Once your organization is connected and upgraded, you will receive a confirmation message. You will then immediately start paying for usage of your Pinecone indexes, including the serverless indexes that were free on the Starter plan. For more details about how costs are calculated, see [Understanding cost](/guides/manage-cost/understanding-cost).

### Pay through the Microsoft Marketplace

To upgrade your plan to Standard or Enterprise and pay through the Microsoft Marketplace, do the following:

1. In the Pinecone console, go to [Settings > Billing > Plans](https://app.pinecone.io/organizations/-/settings/billing/plans).
2. Click **Upgrade** in the **Standard** or **Enterprise** plan section.
3. Click **Billing through Azure**. This takes you to the [Pinecone listing](https://marketplace.microsoft.com/product/saas/pineconesystemsinc1688761585469.pineconesaas) in the Microsoft Marketplace.
4. Click **Get it now**.
5. Select the **Pinecone - Pay As You Go** plan.
6. Click **Subscribe**.
7. On the **Subscribe to Pinecone** page, select the required details and click **Review + subscribe**.

   <Note>The billing unit listed does not reflect the actual cost or metering of costs for Pinecone. See the [Pinecone Pricing page](https://www.pinecone.io/pricing/) for accurate details.</Note>
8. Click **Subscribe**.
9. After the subscription is approved, click **Configure account now**. This redirects you to an Microsoft-specific Pinecone login page.
10. Log in to your Pinecone account. Use the same authentication method as your existing Pinecone organization.
11. Select an organization from the list. You can only connect to organizations that are on the [Starter plan](https://www.pinecone.io/pricing/). Alternatively, you can opt to create a new organization.
12. Click **Connect to Pinecone** and follow the prompts.

Once your organization is connected and upgraded, you will receive a confirmation message. You will then immediately start paying for usage of your Pinecone indexes, including the serverless indexes that were free on the Starter plan. For more details about how costs are calculated, see [Understanding cost](/guides/manage-cost/understanding-cost).


# Chat through the OpenAI-compatible interface
Source: https://docs.pinecone.io/guides/assistant/chat-through-the-openai-compatible-interface

Chat with Pinecone Assistant using the OpenAI-compatible Chat Completion API for inline citations, streaming responses, and easy integration.

After [uploading files](/guides/assistant/manage-files) to an assistant, you can chat with the assistant.

This page shows you how to chat with an assistant using the [OpenAI-compatible chat interface](/reference/api/latest/assistant/chat_completion_assistant). This interface is based on the OpenAI Chat Completion API, a commonly used and adopted API. It is useful if you need inline citations or OpenAI-compatible responses, but has limited functionality compared to the [standard chat interface](/guides/assistant/chat-with-assistant).

<Tip>
  The [standard chat interface](/guides/assistant/chat-with-assistant) is the recommended way to chat with an assistant, as it offers more functionality and control over the assistant's responses and references.
</Tip>

## Chat with an assistant

The [OpenAI-compatible chat interface](/reference/api/latest/assistant/chat_completion_assistant) can return responses in two different formats:

* [Default response](#default-response): The assistant returns a response in a single string field, which includes citation information.
* [Streaming response](#streaming-response): The assistant returns the response as a text stream.

### Default response

The following example sends a message and requests a response in the default format:

<Note>
  The `content` parameter in the request cannot be empty.
</Note>

<CodeGroup>
  ```python Python theme={null}
  # To use the Python SDK, install the plugin:
  # pip install --upgrade pinecone pinecone-plugin-assistant

  from pinecone import Pinecone
  from pinecone_plugins.assistant.models.chat import Message

  pc = Pinecone(api_key="YOUR_API_KEY")

  # Get your assistant.
  assistant = pc.assistant.Assistant(
      assistant_name="example-assistant", 
  )

  # Chat with the assistant.
  chat_context = [Message(role="user", content='What is the maximum height of a red pine?')]
  response = assistant.chat_completions(messages=chat_context)

  print(response)
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone';

  const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' });
  const assistantName = 'example-assistant';

  const assistant = pc.Assistant(assistantName);
  const chatResp = await assistant.chatCompletion({
        messages: [{ role: 'user', content: 'Who is the CFO of Netflix?' }]
      });
  console.log(chatResp);
  ```

  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  ASSISTANT_NAME="example-assistant"

  curl "https://prod-1-data.ke.pinecone.io/assistant/chat/$ASSISTANT_NAME/chat/completions" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "Content-Type: application/json" \
    -H "X-Pinecone-Api-Version: 2025-10" \
    -d '{
    "messages": [
      {
        "role": "user",
        "content": "What is the maximum height of a red pine?"
      }
    ]
  }'
  ```
</CodeGroup>

The example above returns a result like the following:

```JSON theme={null}
{"chat_completion":
  {
    "id":"chatcmpl-9OtJCcR0SJQdgbCDc9JfRZy8g7VJR",
    "choices":[
      {
        "finish_reason":"stop",
        "index":0,
        "message":{
          "role":"assistant",
          "content":"The maximum height of a red pine (Pinus resinosa) is up to 25 meters."
        }
      }
    ],
    "model":"my_assistant"
  }
}
```

### Streaming response

Streaming responses can improve perceived latency by allowing users to see content as it's generated, rather than waiting for the complete response. This creates a more responsive chat experience, especially for longer responses.

The following example sends a message and requests a streaming response:

<Note>
  The `content` parameter in the request cannot be empty.
</Note>

<CodeGroup>
  ```python Python theme={null}
  # To use the Python SDK, install the plugin:
  # pip install --upgrade pinecone pinecone-plugin-assistant

  from pinecone import Pinecone
  from pinecone_plugins.assistant.models.chat import Message

  pc = Pinecone(api_key="YOUR_API_KEY")

  # Get your assistant.
  assistant = pc.assistant.Assistant(
      assistant_name="example-assistant" 
  )

  # Streaming chat with the Assistant.
  chat_context = [Message(role="user", content="What is the maximum height of a red pine?")]
  response = assistant.chat_completions(messages=[chat_context], stream=True)

  for data in response:
      if data:
          print(data)
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone';

  const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' });
  const assistantName = 'example-assistant';
  const assistant = pc.Assistant(assistantName);
  const chatResp = await assistant.chatCompletionStream({
      messages: [{ role: 'user', content: 'Who is the CFO of Netflix?' }]
  });

  for await (const response of chatResp) {
      if (response) {
          console.log(response);
      }
  }
  ```

  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  ASSISTANT_NAME="example-assistant"

  curl "https://prod-1-data.ke.pinecone.io/assistant/chat/$ASSISTANT_NAME/chat/completions" \
    -H "Api-Key: $PINECONE_API_KEY "\
    -H "Content-Type: application/json" \
    -H "X-Pinecone-Api-Version: 2025-10" \
    -d '{
    "messages": [
      {
        "role": "user",
        "content": "What is the maximum height of a red pine?"
      }
    ],
    "stream": true
  }'
  ```
</CodeGroup>

The example above returns a result like the following:

```json theme={null}
{
  'id': '000000000000000009de65aa87adbcf0', 
  'choices': [
      {
      'index': 0, 
      'delta': 
        {
        'role': 'assistant', 
        'content': 'The'
        }, 
      'finish_reason': None
      }
    ], 
  'model': 'gpt-4o-2024-05-13'
}

...

{
  'id': '00000000000000007a927260910f5839',
  'choices': [
      {
      'index': 0,
      'delta':
        {
          'role': '', 
          'content': 'The'
        }, 
      'finish_reason': None
      }
    ], 
  'model': 'gpt-4o-2024-05-13'
}

...

{
  'id': '00000000000000007a927260910f5839', 
  'choices': [
    {
      'index': 0, 
      'delta': 
        {
        'role': None, 
        'content': None
        }, 
      'finish_reason': 'stop'
      }
    ], 
  'model': 'gpt-4o-2024-05-13'
}
```

There are three types of messages in a chat completion response:

* **Message start**: Includes `"role":"assistant"`, which indicates that the assistant is responding to the user's message.
* **Content**: Includes a value in the `content` field (e.g., `"content":"The"`), which is part of the assistant's streamed response to the user's message.
* **Message end**: Includes `"finish_reason":"stop"`, which indicates that the assistant has finished responding to the user's message.

## Extract the response content

In the assistant's response, the message string is contained in the following JSON object:

* `choices.[0].message.content` for the default chat response
* `choices[0].delta.content` for the streaming chat response

You can extract the message content and print it to the console:

<Tabs>
  <Tab title="Default response">
    <CodeGroup>
      ```python Python theme={null}
      print(str(response.choices[0].message.content))
      ```

      ```bash curl theme={null}
      | jq '.choices.[0].message.content'
      ```
    </CodeGroup>

    This creates output like the following:

    ```bash theme={null}
    A red pine, scientifically known as *Pinus resinosa*, is a medium-sized tree that can grow up to 25 meters high and 75 centimeters in diameter. [1, pp. 1]
    ```
  </Tab>

  <Tab title="Streaming response">
    <CodeGroup>
      ```python Python theme={null}
      for data in response:
          if data:
              print(str(data.choices[0].delta.content))
      ```

      ```bash curl theme={null}
      |  sed -u 's/.*"content":"\([^"]*\)".*/\1/'
      ```
    </CodeGroup>

    This creates output like the following:

    ```bash Streaming response theme={null}
    The
     maximum
     height
     of
     a
     red
     pine
     (
    Pin
    us
     resin
    osa
    )
     is
     up
     to
     twenty
    -five
     meters

     [1, pp. 1]
    .
    ```
  </Tab>
</Tabs>

## Choose a model

Pinecone Assistant supports the following models:

* `gpt-4o` (default)
* `gpt-4.1`
* `gpt-5`
* `o4-mini`
* `claude-sonnet-4-5`
* `gemini-2.5-pro`

<Note>
  Anthropic has [deprecated](https://platform.claude.com/docs/en/about-claude/model-deprecations) the Claude 3.5 Sonnet and Claude 3.7 Sonnet models. Assistant automatically routes chat requests that specify `claude-3-5-sonnet` or `claude-3-7-sonnet` to `claude-sonnet-4-5` at the same price.
</Note>

<Tip>
  For chat applications, we recommend using GPT models (`gpt-4o`, `gpt-4.1`, `gpt-5`, or `o4-mini`) as they typically provide faster response times compared to other models.
</Tip>

To choose a non-default model for your assistant, set the `model` parameter in the request:

<CodeGroup>
  ```python Python theme={null}
  # To use the Python SDK, install the plugin:
  # pip install --upgrade pinecone pinecone-plugin-assistant

  from pinecone import Pinecone
  from pinecone_plugins.assistant.models.chat import Message

  pc = Pinecone(api_key="YOUR_API_KEY")

  # Get your assistant.
  assistant = pc.assistant.Assistant(
      assistant_name="example-assistant", 
  )

  # Chat with the assistant.
  chat_context = [Message(role="user", content="What is the maximum height of a red pine?")]
  response = assistant.chat_completions(
      messages=chat_context, 
      model="gpt-4.1"
  )
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone';

  const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' });

  const assistantName = 'example-assistant';
  const assistant = pc.Assistant(assistantName);
  const chatResp = await assistant.chatCompletion({
    messages: [{ role: 'user', content: 'What is the maximum height of a red pine?' }],
    model: 'gpt-4.1',
  });

  console.log(chatResp);
  ```

  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  ASSISTANT_NAME="example-assistant"

  curl "https://prod-1-data.ke.pinecone.io/assistant/chat/$ASSISTANT_NAME/chat/completions" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "Content-Type: application/json" \
    -H "X-Pinecone-Api-Version: 2025-10" \
    -d '{
    "messages": [
      {
        "role": "user",
        "content": "What is the maximum height of a red pine?"
      }
    ],
    "model": "gpt-4.1"
  }'
  ```
</CodeGroup>

## Filter chat with metadata

You can [filter which documents to use for chat completions](/guides/assistant/files-overview#file-metadata). The following example filters the responses to use only documents that include the metadata `"resource": "encyclopedia"`.

<CodeGroup>
  ```python Python theme={null}
  # To use the Python SDK, install the plugin:
  # pip install --upgrade pinecone pinecone-plugin-assistant

  from pinecone import Pinecone
  from pinecone_plugins.assistant.models.chat import Message

  pc = Pinecone(api_key="YOUR_API_KEY")

  # Get your assistant.
  assistant = pc.assistant.Assistant(
      assistant_name="example-assistant", 
  )

  # Chat with the assistant.
  chat_context = [Message(role="user", content="What is the maximum height of a red pine?")]
  response = assistant.chat_completions(messages=chat_context, stream=True, filter={"resource": "encyclopedia"})
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone';

  const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' });
  const assistantName = 'example-assistant';
  const assistant = pc.Assistant(assistantName);
  const chatResp = await assistant.chatCompletion({
    messages: [{ role: 'user', content: 'What is the maximum height of a red pine?' }],
    filter: {
      'resource': 'encyclopedia'
    }
  });
  console.log(chatResp);
  ```

  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  ASSISTANT_NAME="example-assistant"

  curl "https://prod-1-data.ke.pinecone.io/assistant/chat/$ASSISTANT_NAME/chat/completions" \
    -H "Api-Key: $PINECONE_API_KEY "\
    -H "Content-Type: application/json" \
    -H "X-Pinecone-Api-Version: 2025-10" \
    -d '{
    "messages": [
      {
        "role": "user",
        "content": "What is the maximum height of a red pine?"
      }
    ],
    "stream": true,
    "filter": 
      {
      "resource": "encyclopedia"
      }
    }'
  ```
</CodeGroup>

## Set the sampling temperature

<Note>
  This is available in API versions `2025-04` and later.
</Note>

Temperature is a parameter that controls the randomness of a model's predictions during text generation. Lower temperatures (\~0.0) yield more consistent, predictable answers, while higher temperatures increase the model's explanatory power and is generally better for creative tasks.

To control the sampling temperature for a model, set the `temperarture` parameter in the request. If a model does not support a temperature parameter, the parameter is ignored.

<CodeGroup>
  ```python Python theme={null}
  # To use the Python SDK, install the plugin:
  # pip install --upgrade pinecone pinecone-plugin-assistant

  from pinecone import Pinecone
  from pinecone_plugins.assistant.models.chat import Message

  pc = Pinecone(api_key="YOUR_API_KEY")
  assistant = pc.assistant.Assistant(assistant_name="example-assistant")

  msg = Message(role="user", content="Who is the CFO of Netflix?")
  response = assistant.chat_completions(
      messages=[msg], 
      temperature=0.8
  )

  print(response)
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone';

  const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' });

  const assistantName = 'example-assistant';
  const assistant = pc.Assistant(assistantName);
  const chatResp = await assistant.chatCompletion({
    messages: [{ role: 'user', content: 'Who is the CFO of Netflix?' }],
    temperature: 0.8,
  });
  console.log(chatResp);
  ```

  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  ASSISTANT_NAME="example-assistant"

  curl "https://prod-1-data.ke.pinecone.io/assistant/chat/$ASSISTANT_NAME/chat/completions" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "Content-Type: application/json" \
    -H "X-Pinecone-Api-Version: 2025-10" \
    -d '{
    "messages": [
      {
        "role": "user",
        "content": "Who is the CFO of Netflix?"
      }
    ],
    "temperature": 0.8
  }'
  ```
</CodeGroup>


# Chat through the standard interface
Source: https://docs.pinecone.io/guides/assistant/chat-with-assistant

Chat with Pinecone Assistant through the standard interface with default, streaming, or JSON responses, plus citations and chat history support.

After [uploading files](/guides/assistant/manage-files) to an assistant, you can chat with the assistant.

<Tip>
  You can chat with an assistant using the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/assistant). Select the assistant to chat with, and use the Assistant playground.
</Tip>

## Chat through the standard interface

The [standard chat interface](/reference/api/latest/assistant/chat_assistant) can return responses in three different formats:

* [Default response](#default-response): The assistant returns a structured response and separate citation information.
* [Streaming response](#streaming-response): The assistant returns the response as a text stream.
* [JSON response](#json-response): The assistant returns the response as JSON key-value pairs.

<Tip>
  This is the recommended way to chat with an assistant, as it offers more functionality and control over the assistant's responses and references. However, if you need your assistant to be OpenAI-compatible or need inline citations, use the [OpenAI-compatible chat interface](#chat-through-the-openai-compatible-interface).
</Tip>

### Default response

The following example sends a message and requests a default response:

<Note>
  The `content` parameter in the request cannot be empty.
</Note>

<CodeGroup>
  ```python Python theme={null}
  # To use the Python SDK, install the plugin:
  # pip install --upgrade pinecone pinecone-plugin-assistant

  from pinecone import Pinecone
  from pinecone_plugins.assistant.models.chat import Message

  pc = Pinecone(api_key="YOUR_API_KEY")
  assistant = pc.assistant.Assistant(assistant_name="example-assistant")

  msg = Message(role="user", content="Who is the CFO of Netflix?")
  response = assistant.chat(messages=[msg])

  # Alternatively, you can provide a dictionary as the message:
  # msg = {"role": "user", "content": "Who is the CFO of Netflix?"}
  # response = assistant.chat(messages=[msg])

  print(response)

  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone';

  const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' });

  const assistantName = 'example-assistant';
  const assistant = pc.Assistant(assistantName);
  const chatResp = await assistant.chat({
    messages: [{ role: 'user', content: 'Who is the CFO of Netflix?' }],
  });
  console.log(chatResp);
  ```

  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  ASSISTANT_NAME="example-assistant"

  curl "https://prod-1-data.ke.pinecone.io/assistant/chat/$ASSISTANT_NAME" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "Content-Type: application/json" \
    -H "X-Pinecone-Api-Version: 2025-10" \
    -d '{
    "messages": [
      {
        "role": "user",
        "content": "Who is the CFO of Netflix?"
      }
    ],
    "stream": false,
    "model": "gpt-4o"
  }'
  ```
</CodeGroup>

The example above returns a result like the following:

```json JSON theme={null}
{
    "finish_reason": "stop",
    "message": {
        "role": "assistant",
        "content": "The Chief Financial Officer (CFO) of Netflix is Spencer Neumann."
    },
    "id": "00000000...",
    "model": "gpt-4o-2024-11-20",
    "usage": {
        "prompt_tokens": 23633,
        "completion_tokens": 24,
        "total_tokens": 23657
    },
    "citations": [
        {
            "position": 63,
            "references": [
                {
                    "file": {
                        "status": "Available",
                        "id": "76a11dd1...",
                        "name": "Netflix-10-K-01262024.pdf",
                        "size": 1073470,
                        "metadata": {
                            "company": "netflix",
                            "document_type": "form 10k"
                        },
                        "updated_on": "2025-07-16T16:46:40.787204651Z",
                        "created_on": "2025-07-16T16:45:59.414273474Z",
                        "signed_url": "https://storage.googleapis.com/..."
                    },
                    "pages": [
                        78,
                        79,
                        80
                    ],
                    "highlight": null
                }
            ]
        }
    ]
}
```

<Warning>
  [`signed_url`](https://cloud.google.com/storage/docs/access-control/signed-urls) provides temporary, read-only access to the relevant file. Anyone with the link can access the file, so treat it as sensitive data. Expires in one hour.
</Warning>

### Streaming response

Streaming responses can improve perceived latency by allowing users to see content as it's generated, rather than waiting for the complete response. This creates a more responsive chat experience, especially for longer responses.

The following example sends a message and requests a streaming response:

<Note>
  The `content` parameter in the request cannot be empty.
</Note>

<CodeGroup>
  ```python Python theme={null}
  # To use the Python SDK, install the plugin:
  # pip install --upgrade pinecone pinecone-plugin-assistant

  from pinecone import Pinecone
  from pinecone_plugins.assistant.models.chat import Message

  pc = Pinecone(api_key="YOUR_API_KEY")

  assistant = pc.assistant.Assistant(assistant_name="example-assistant")

  msg = Message(role="user", content="What is the inciting incident of Pride and Prejudice?")

  response = assistant.chat(messages=[msg], stream=True)

  for data in response:
      if data:
          print(data)
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone';

  const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' });
  const assistantName = 'example-assistant';

  const assistant = pc.Assistant(assistantName);
  const chatResp = await assistant.chatStream({
        messages: [{ role: 'user', content: 'Who is the CFO of Netflix?' }]
      });

  for await (const response of chatResp) {
      if (response) {
          console.log(response);
      }
  }
  ```

  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  ASSISTANT_NAME="example-assistant"

  curl "https://prod-1-data.ke.pinecone.io/assistant/chat/$ASSISTANT_NAME" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "Content-Type: application/json" \
    -H "X-Pinecone-Api-Version: 2025-10" \
    -d '{
    "messages": [
      {
        "role": "user",
        "content": "What is the inciting incident of Pride and Prejudice?"
      }
    ],
    "stream": true,
    "model": "gpt-4o"
  }'
  ```
</CodeGroup>

The example above returns a result like the following:

```shell theme={null}
data:{"type":"message_start","id":"0000000000000000111b35de85e8a8f9","model":"gpt-4o-2024-05-13","role":"assistant"}

data:{"type":"content_chunk","id":"0000000000000000111b35de85e8a8f9","model":"gpt-4o-2024-05-13","delta":{"content":"The"}}

...

data:{"type":"citation","id":"0000000000000000111b35de85e8a8f9","model":"gpt-4o-2024-05-13","citation":{"position":406,"references":[{"file":{"status":"Available","id":"ae79e447-b89e-4994-994b-3232ca52a654","name":"Pride-and-Prejudice.pdf","size":2973077,"metadata":null,"updated_on":"2024-06-14T15:01:57.385425746Z","created_on":"2024-06-14T15:01:02.910452398Z","signed_url":"https://storage.googleapis.com/..."},"pages":[1]}]}}

data:{"type":"message_end","id":"0000000000000000111b35de85e8a8f9","model":"gpt-4o-2024-05-13","finish_reason":"stop","usage":{"prompt_tokens":9736,"completion_tokens":102,"total_tokens":9838}}
```

There are four types of messages in a streaming chat response:

* **Message start**: Includes `"role":"assistant"`, which indicates that the assistant is responding to the user's message.
* **Content**: Includes a value in the `content` field (e.g., `"content":"The"`), which is part of the assistant's streamed response to the user's message.
* **Citation**: Includes a citation to the document that the assistant used to generate the response.
* **Message end**: Includes `"finish_reason":"stop"`, which indicates that the assistant has finished responding to the user's message.

### JSON response

The following example uses the `json_response` parameter to instruct the assistant to return the response as JSON key-value pairs. This is useful if you need to parse the response programmatically.

<Note>
  JSON response cannot be used with the `stream` parameter.
</Note>

<CodeGroup>
  ```python Python theme={null}
  # To use the Python SDK, install the plugin:
  # pip install --upgrade pinecone pinecone-plugin-assistant

  import json
  from pinecone import Pinecone
  from pinecone_plugins.assistant.models.chat import Message

  pc = Pinecone(api_key="YOUR_API_KEY")

  assistant = pc.assistant.Assistant(assistant_name="example-assistant")

  msg = Message(role="user", content="Who is the CFO and CEO of Netflix?")

  response = assistant.chat(messages=[msg], json_response=True)

  print(json.loads(response))
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone';

  const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' });

  const assistantName = 'example-assistant';
  const assistant = pc.Assistant(assistantName);
  const chatResp = await assistant.chat({
    messages: [{ role: 'user', content: 'Who is the CFO and CEO of Netflix?', json_response: true }],
  });
  console.log(chatResp);
  ```

  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  ASSISTANT_NAME="example-assistant"

  curl "https://prod-1-data.ke.pinecone.io/assistant/chat/$ASSISTANT_NAME" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "Content-Type: application/json" \
    -H "X-Pinecone-Api-Version: 2025-10" \
    -d '{
    "messages": [
      {
        "role": "user",
        "content": "Who is the CFO and CEO of Netflix?"
      }
    ],
    "json_response": true,
    "model": "gpt-4o"
  }'
  ```
</CodeGroup>

The example above returns a result like the following:

```json theme={null}
{
  "finish_reason": "stop",
  "message": {
    "role": "assistant",
    "content": "{\"CFO\": \"Spencer Neumann\", \"CEO\": \"Ted Sarandos and Greg Peters\"}"
  },
  "id": "0000000000000000680c95d2faab7aad",
  "model": "gpt-4o-2024-11-20",
  "usage": {
    "prompt_tokens": 14298,
    "completion_tokens": 42,
    "total_tokens": 14340
  },
  "citations": [
    {
      "position": 24,
      "references": [
        {
          "file": {
            "status": "Available",
            "id": "cbecaa37-2943-4030-b4d6-ce4350ab774a",
            "name": "Netflix-10-K-01262024.pdf",
            "size": 1073470,
            "metadata": {
              "test-key": "test-value"
            },
            "updated_on": "2025-01-24T16:53:17.148820770Z",
            "created_on": "2025-01-24T16:52:44.851577534Z",
            "signed_url": "https://storage.googleapis.com/knowledge-prod-files/bf0dcf22..."
          },
          "pages": [
            79
          ],
          "highlight": null
        },
    ...
  ]
}
```

## Extract the response content

In the assistant's response, the message string is contained in the following JSON object:

* `message.content` for the default chat response
* `delta.content` for the streaming chat response
* `message.content` for the JSON response

You can extract the message content and print it to the console:

<Tabs>
  <Tab title="Default response">
    <CodeGroup>
      ```python Python theme={null}
      msg = Message(role="user", content="What is the maximum height of a red pine?")

      response = assistant.chat(messages=[msg])

      print(str(response.message.content))
      ```

      ```javascript JavaScript theme={null}
      const assistant = pc.Assistant(assistantName);
      const chatResp = await assistant.chat({
        messages: [{ role: 'user', content: 'What is the maximum height of a red pine?' }],
      });
      console.log(chatResp.message.content);
      ```

      ```bash curl theme={null}
      | jq '.message.content'
      ```
    </CodeGroup>

    This creates output like the following:

    ```bash theme={null}
    A red pine, scientifically known as *Pinus resinosa*, is a medium-sized tree that can grow up to 25 meters high and 75 centimeters in diameter. [1, pp. 1]
    ```
  </Tab>

  <Tab title="Streaming response">
    <CodeGroup>
      ```python Python theme={null}
      msg = Message(role="user", content="What is the maximum height of a red pine?")

      response = assistant.chat(messages=[msg], stream=True)

      for data in response:
          if hasattr(data, "delta"):
              print(data.delta.content)
      ```

      ```bash curl theme={null}
      |  sed -u 's/.*"content":"\([^"]*\)".*/\1/'
      ```
    </CodeGroup>

    This creates output like the following:

    ```bash Streaming response theme={null}
    The
     maximum
     height
     of
     a
     red
     pine
     (
    Pin
    us
     resin
    osa
    )
     is
     up
     to
     twenty
    -five
     meters

     [1, pp. 1]
    .
    ```
  </Tab>

  <Tab title="JSON response">
    <CodeGroup>
      ```python Python theme={null}
      import json

      msg = Message(role="user", content="What is the maximum height of a red pine?")

      response = assistant.chat(messages=[msg], json_response=True)

      print(json.loads(response.message.content))
      ```

      ```bash curl theme={null}
      |  sed -u 's/.*"content":"\([^"]*\)".*/\1/'
      ```
    </CodeGroup>

    This creates output like the following:

    ```bash JSON response theme={null}
    {'red pine': 'A red pine, scientifically known as *Pinus resinosa*, is a medium-sized tree that can grow up to 25 meters high and 75 centimeters in diameter.'}
    ```
  </Tab>
</Tabs>

## Choose a model

Pinecone Assistant supports the following models:

* `gpt-4o` (default)
* `gpt-4.1`
* `gpt-5`
* `o4-mini`
* `claude-sonnet-4-5`
* `gemini-2.5-pro`

<Note>
  Anthropic has [deprecated](https://platform.claude.com/docs/en/about-claude/model-deprecations) the Claude 3.5 Sonnet and Claude 3.7 Sonnet models. Assistant automatically routes chat requests that specify `claude-3-5-sonnet` or `claude-3-7-sonnet` to `claude-sonnet-4-5` at the same price.
</Note>

<Tip>
  For chat applications, we recommend using GPT models (`gpt-4o`, `gpt-4.1`, `gpt-5`, or `o4-mini`) as they typically provide faster response times compared to other models.
</Tip>

To choose a non-default model for your assistant, set the `model` parameter in the request:

<CodeGroup>
  ```python Python theme={null}
  # To use the Python SDK, install the plugin:
  # pip install --upgrade pinecone pinecone-plugin-assistant

  from pinecone import Pinecone
  from pinecone_plugins.assistant.models.chat import Message

  pc = Pinecone(api_key="YOUR_API_KEY")

  # Get your assistant.
  assistant = pc.assistant.Assistant(
      assistant_name="example-assistant", 
  )

  # Chat with the assistant.
  chat_context = [Message(role="user", content="What is the maximum height of a red pine?")]
  response = assistant.chat(
      messages=chat_context, 
      model="gpt-4.1"
  )
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone';

  const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' });

  const assistantName = 'example-assistant';
  const assistant = pc.Assistant(assistantName);
  const chatResp = await assistant.chat({
    messages: [{ role: 'user', content: 'What is the maximum height of a red pine?' }],
    model: 'gpt-4.1',
  });

  console.log(chatResp);
  ```

  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  ASSISTANT_NAME="example-assistant"

  curl "https://prod-1-data.ke.pinecone.io/assistant/chat/$ASSISTANT_NAME" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "Content-Type: application/json" \
    -H "X-Pinecone-Api-Version: 2025-10" \
    -d '{
    "messages": [
      {
        "role": "user",
        "content": "What is the maximum height of a red pine?"
      }
    ],
    "model": "gpt-4.1"
  }'
  ```
</CodeGroup>

## Provide conversation history

Models lack memory of previous requests, so any relevant messages from earlier in the conversation must be present in the `messages` object.

In the following example, the `messages` object includes prior messages that are necessary for interpreting the newest message.

<CodeGroup>
  ```python Python theme={null}
  # To use the Python SDK, install the plugin:
  # pip install --upgrade pinecone pinecone-plugin-assistant

  from pinecone import Pinecone
  from pinecone_plugins.assistant.models.chat import Message

  pc = Pinecone(api_key="YOUR_API_KEY")

  # Get your assistant.
  assistant = pc.assistant.Assistant(
      assistant_name="example-assistant", 
  )

  # Chat with the assistant.
  chat_context = [
      Message(content="What is the maximum height of a red pine?", role="user"),
      Message(content="The maximum height of a red pine (Pinus resinosa) is up to 25 meters.", role="assistant"),
      Message(content="What is its maximum diameter?", role="user")
  ]
  response = assistant.chat(messages=chat_context)
  ```

  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  ASSISTANT_NAME="example-assistant"

  curl "https://prod-1-data.ke.pinecone.io/assistant/chat/$ASSISTANT_NAME" \
    -H "Api-Key: $PINECONE_API_KEY " \
    -H "Content-Type: application/json" \
    -H "X-Pinecone-Api-Version: 2025-10" \
    -d '{
    "messages": [
      {
        "role": "user",
        "content": "What is the maximum height of a red pine?"
      },
      {
        "role": "assistant",
        "content": "The maximum height of a red pine (Pinus resinosa) is up to 25 meters."
      },
      {
        "role": "user",
        "content": "What is its maximum diameter?"
      }
    ]
  }'
  ```
</CodeGroup>

The example returns a response like the following:

```JSON theme={null}
{
  "finish_reason":"stop",
  "message":{
    "role":"assistant",
    "content":"The maximum diameter of a red pine (Pinus resinosa) is up to 1 meter."
    },
    "id":"0000000000000000236a24a17e55309a",
    "model":"gpt-4o-2024-05-13",
    "usage":{
      "prompt_tokens":21377,
      "completion_tokens":20,
      "total_tokens":21397
      },
      "citations":[...]
}
```

## Filter chat with metadata

You can [filter which documents to use for chat completions](/guides/assistant/files-overview#file-metadata). The following example filters the responses to use only documents that include the metadata `"resource": "encyclopedia"`.

<CodeGroup>
  ```python Python theme={null}
  # To use the Python SDK, install the plugin:
  # pip install --upgrade pinecone pinecone-plugin-assistant

  from pinecone import Pinecone
  from pinecone_plugins.assistant.models.chat import Message

  pc = Pinecone(api_key="YOUR_API_KEY")

  # Get your assistant.
  assistant = pc.assistant.Assistant(
      assistant_name="example-assistant", 
  )

  # Chat with the assistant.
  chat_context = [Message(role="user", content="What is the maximum height of a red pine?")]
  response = assistant.chat(messages=chat_context, stream=True, filter={"resource": "encyclopedia"})
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone';

  const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' });
  const assistantName = 'example-assistant';
  const assistant = pc.Assistant(assistantName);
  const chatResp = await assistant.chat({
    messages: [{ role: 'user', content: 'What is the maximum height of a red pine?' }],
    filter: {
      'resource': 'encyclopedia'
    }
  });
  console.log(chatResp);
  ```

  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  ASSISTANT_NAME="example-assistant"

  curl "https://prod-1-data.ke.pinecone.io/assistant/chat/$ASSISTANT_NAME" \
    -H "Api-Key: $PINECONE_API_KEY "\
    -H "Content-Type: application/json" \
    -H "X-Pinecone-Api-Version: 2025-10" \
    -d '{
    "messages": [
      {
        "role": "user",
        "content": "What is the maximum height of a red pine?"
      }
    ],
    "stream": true,
    "filter": 
      {
      "resource": "encyclopedia"
      }
    }'
  ```
</CodeGroup>

## Control the context size

<Note>
  This is available in API versions `2025-04` and later.
</Note>

To limit the number of [input tokens](/guides/assistant/pricing-and-limits#token-usage) used, you can control the context size by tuning `top_k * snippet_size`. These parameters can be adjusted by setting [`context_options`](/reference/api/latest/assistant/chat_assistant#body-context-options) in the request:

* `snippet_size`: Controls the max size of a snippet (default is 2048 tokens). Note that snippet size can vary and, in rare cases, may be bigger than the set `snippet_size`. Snippet size controls the amount of context the model is given for each chunk of text.
* `top_k`: Controls the max number of context snippets sent to the LLM (default is 16). `top_k` controls the diversity of information sent to the model.

While additional tokens will be used for other parameters (e.g., the system prompt, chat input), adjusting the `top_k` and `snippet_size` can help manage token consumption.

<CodeGroup>
  ```python Python theme={null}
  # To use the Python SDK, install the plugin:
  # pip install --upgrade pinecone pinecone-plugin-assistant

  from pinecone import Pinecone
  from pinecone_plugins.assistant.models.chat import Message

  pc = Pinecone(api_key="YOUR_API_KEY")
  assistant = pc.assistant.Assistant(assistant_name="example-assistant")

  msg = Message(role="user", content="Who is the CFO of Netflix?")
  response = assistant.chat(messages=[msg], context_options={"snippet_size": 2500, "top_k": 10})

  print(response)
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone';

  const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' });

  const assistantName = 'example-assistant';
  const assistant = pc.Assistant(assistantName);
  const chatResp = await assistant.chat({
    messages: [{ role: 'user', content: 'Who is the CFO of Netflix?' }],
    contextOptions: { topK: 10, snippetSize: 2500 },
  });

  console.log(chatResp);
  ```

  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  ASSISTANT_NAME="example-assistant"

  curl "https://prod-1-data.ke.pinecone.io/assistant/chat/$ASSISTANT_NAME" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "Content-Type: application/json" \
    -H "X-Pinecone-Api-Version: 2025-10" \
    -d '{
    "messages": [
      {
        "role": "user",
        "content": "Who is the CFO of Netflix?"
      }
    ],
    "context_options": {
      "top_k":10,
      "snippet_size":2500
      }
  }'
  ```
</CodeGroup>

The example will return up to 10 snippets and each snippet will be up to 2500 tokens in size.

<Tip>
  To better understand the context retrieved using these parameters, you can [retrieve context from an assistant](/reference/api/latest/assistant/context_assistant).
</Tip>

## Set the sampling temperature

<Note>
  This is available in API versions `2025-04` and later.
</Note>

Temperature is a parameter that controls the randomness of a model's predictions during text generation. Lower temperatures (\~0.0) yield more consistent, predictable answers, while higher temperatures increase the model's explanatory power and is generally better for creative tasks.

To control the sampling temperature for a model, set the `temperarture` parameter in the request. If a model does not support a temperature parameter, the parameter is ignored.

<CodeGroup>
  ```python Python theme={null}
  # To use the Python SDK, install the plugin:
  # pip install --upgrade pinecone pinecone-plugin-assistant

  from pinecone import Pinecone
  from pinecone_plugins.assistant.models.chat import Message

  pc = Pinecone(api_key="YOUR_API_KEY")
  assistant = pc.assistant.Assistant(assistant_name="example-assistant")

  msg = Message(role="user", content="Who is the CFO of Netflix?")
  response = assistant.chat(
      messages=[msg], 
      temperature=0.8
  )

  print(response)
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone';

  const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' });

  const assistantName = 'example-assistant';
  const assistant = pc.Assistant(assistantName);
  const chatResp = await assistant.chat({
    messages: [{ role: 'user', content: 'Who is the CFO of Netflix?' }],
    temperature: 0.8,
  });
  console.log(chatResp);
  ```

  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  ASSISTANT_NAME="example-assistant"

  curl "https://prod-1-data.ke.pinecone.io/assistant/chat/$ASSISTANT_NAME" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "Content-Type: application/json" \
    -H "X-Pinecone-Api-Version: 2025-10" \
    -d '{
    "messages": [
      {
        "role": "user",
        "content": "Who is the CFO of Netflix?"
      }
    ],
    "temperature": 0.8
  }'
  ```
</CodeGroup>

## Include citation highlights in the response

<Note>
  Citation highlights are available in the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/assistant) or API versions `2025-04` and later.
</Note>

When using the [standard chat interface](/reference/api/latest/assistant/chat_assistant), every response includes a `citation` object. The object includes a reference to the document that the assistant used to generate the response. Additionally, you can include highlights, which are the specific parts of the document that the assistant used to generate the response, by setting the `include_highlights` parameter to `true` in the request:

```bash curl theme={null}
PINECONE_API_KEY="YOUR_API_KEY"
ASSISTANT_NAME="example-assistant"

curl "https://prod-1-data.ke.pinecone.io/assistant/chat/$ASSISTANT_NAME" \
  -H "Api-Key: $PINECONE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Pinecone-Api-Version: 2025-10" \
  -d '{
  "messages": [
    {
      "role": "user",
      "content": "Who is the CFO of Netflix?"
    }
  ],
  "stream": false,
  "model": "gpt-4o",
  "include_highlights": true
}'
```

The example returns response like the following:

```json theme={null}
{
  "finish_reason":"stop",
  "message":{
    "role":"assistant",
    "content":"The Chief Financial Officer (CFO) of Netflix is Spencer Neumann."
    },
    "id":"00000000000000006685b07087b1ad42",
    "model":"gpt-4o-2024-05-13",
    "usage":{
      "prompt_tokens":12490,
      "completion_tokens":33,
      "total_tokens":12523
      },
      "citations":[{
        "position":63,
        "references":[{
          "file":{
            "status":"Available",
            "id":"cbecaa37-2943-4030-b4d6-ce4350ab774a",
            "name":"Netflix-10-K-01262024.pdf",
            "size":1073470,
            "metadata":{"test-key":"test-value"},
            "updated_on":"2025-01-24T16:53:17.148820770Z",
            "created_on":"2025-01-24T16:52:44.851577534Z",
            "signed_url":"https://storage.googleapis.com/knowledge-prod-files/b..."
            },
            "pages":[78],
            "highlight":{
              "type":"text",
              "content":"EXHIBIT 31.3\nCERTIFICATION OF CHIEF FINANCIAL OFFICER\nPURSUANT TO SECTION 302 OF THE SARBANES-OXLEY ACT OF 2002\nI, Spencer Neumann, certify that:"
              }
            },
            {
              "file":{
                "status":"Available",
                "id":"cbecaa37-2943-4030-b4d6-ce4350ab774a",
                "name":"Netflix-10-K-01262024.pdf",
                "size":1073470,
                "metadata":{"test-key":"test-value"},
                "updated_on":"2025-01-24T16:53:17.148820770Z",
                "created_on":"2025-01-24T16:52:44.851577534Z",
                "signed_url":"https://storage.googleapis.com/knowledge-prod-files/bf..."
                },
                "pages":[79],
                "highlight":{
                  "type":"text",
                  "content":"operations of\nNetflix, Inc.\nDated: January 26, 2024  By:  /S/ SPENCER NEUMANN\n  Spencer Neumann\n  Chief Financial Officer"
                }
            }
          ]
        }
      ]
}
```

<Note>
  Enabling highlights will increase token usage.
</Note>


# Context snippets overview
Source: https://docs.pinecone.io/guides/assistant/context-snippets-overview

Learn how Pinecone Assistant retrieves context snippets with relevancy scores and references for RAG applications and agentic workflows.

You can [retrieve the context snippets](/guides/assistant/retrieve-context-snippets) that Pinecone Assistant uses to generate its responses. This data includes relevant chunks, relevancy scores, and references.

## Use cases

Retrieving context snippets is useful for performing tasks like the following:

* Understanding what relevant data snippets Pinecone Assistant is providing to the LLM for chat generation.
* Using the retrieved snippets with your own LLM.
* Using the retrieved snippets with your own RAG application or agentic workflow.

## SDK support

The Pinecone [Python SDK](/reference/sdks/python/overview) and [Node.js SDK](/reference/sdks/node/overview) provide convenient programmatic access to [retrieve context snippets](/reference/api/latest/assistant/context_assistant).

## Pricing

Context retrieval usage is [measured in tokens](/guides/assistant/pricing-and-limits#token-usage), similar to Pinecone Assistant. See [Pricing](https://www.pinecone.io/pricing/) for up-to-date pricing information.

<Note>
  Pricing updates specific to context retrieval will be made as the feature becomes generally available.
</Note>


# Create an assistant
Source: https://docs.pinecone.io/guides/assistant/create-assistant

Create a Pinecone Assistant with custom instructions, metadata, and region settings using the API, Python SDK, Node.js SDK, or console.

This page shows you how to create an [assistant](/guides/assistant/overview).

You can [create an assistant](/reference/api/latest/assistant/create_assistant), as in the following example:

<CodeGroup>
  ```python Python theme={null}
  # To use the Python SDK, install the plugin:
  # pip install --upgrade pinecone pinecone-plugin-assistant

  from pinecone import Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")

  assistant = pc.assistant.create_assistant(
      assistant_name="example-assistant", 
      instructions="Use American English for spelling and grammar.", # Description or directive for the assistant to apply to all responses.
      metadata={"team": "customer-support", "version": "1.0"}, # Optional metadata (max 16KB) for organizing assistants.
      region="us", # Region to deploy assistant. Options: "us" (default) or "eu".
      timeout=30 # Maximum seconds to wait for assistant status to become "Ready" before timing out.
  )
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone';

  const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' });

  const assistant = await pc.createAssistant({
    name: 'example-assistant',
    instructions: 'Use American English for spelling and grammar.',
    metadata: { team: 'customer-support', version: '1.0' }, // Optional metadata (max 16KB) for organizing assistants.
    region: 'us'
  });
  ```

  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"

  curl "https://api.pinecone.io/assistant/assistants" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "name": "example-assistant",
    "instructions": "Use American English for spelling and grammar.",
    "metadata": {"team": "customer-support", "version": "1.0"},
    "region":"us"
  }'
  ```
</CodeGroup>

<Note>
  Instructions (maximum size 16 KB) are included in every chat API call. Longer instructions increase input token costs for each request and consume more of the LLM's context window, reducing available space for retrieved context and conversation history.
</Note>

<Tip>
  You can create an assistant using the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/assistant/-/files).
</Tip>


# Evaluate answers
Source: https://docs.pinecone.io/guides/assistant/evaluate-answers

Evaluate RAG system answers with Pinecone Assistant using correctness, completeness, and alignment metrics against a ground truth answer.

This page shows you how to [evaluate responses](/guides/assistant/evaluation-overview) from an assistant or other RAG systems using the `metrics_alignment` operation.

You can [evaluate a response](/reference/api/latest/assistant/metrics_alignment) from an assistant, as in the following example:

<CodeGroup>
  ```python Python theme={null}
  # To use the Python SDK, install the plugin:
  # pip install --upgrade pinecone pinecone-plugin-assistant
  # pip install requests

  import requests
  from pinecone_plugins.assistant.models.chat import Message

  payload = {
      "question": "What are the capital cities of France, England and Spain?", # Question to ask the assistant.
      "answer": "Paris is the capital city of France and Barcelona of Spain", # Answer from the assistant.
      "ground_truth_answer": "Paris is the capital city of France, London of England and Madrid of Spain." # Expected answer to evaluate the assistant's response.
  }

  headers = {
      "Api-Key": "YOUR_API_KEY",
      "Content-Type": "application/json"
  }

  url = "https://prod-1-data.ke.pinecone.io/assistant/evaluation/metrics/alignment"

  response = requests.request("POST", url, json=payload, headers=headers)

  print(response.text)
  ```

  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"

  curl "https://prod-1-data.ke.pinecone.io/assistant/evaluation/metrics/alignment" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "question": "What are the capital cities of France, England and Spain?",
    "answer": "Paris is the capital city of France and Barcelona of Spain",
    "ground_truth_answer": "Paris is the capital city of France, London of England and Madrid of Spain"
  }'
  ```
</CodeGroup>

```json Response theme={null}
{
  "metrics": {
    "correctness": 0.5,
    "completeness": 0.3333,
    "alignment": 0.4
  },
  "reasoning": {
    "evaluated_facts": [
      {
        "fact": {
          "content": "Paris is the capital city of France."
        },
        "entailment": "entailed"
      },
      {
        "fact": {
          "content": "London is the capital city of England."
        },
        "entailment": "neutral"
      },
      {
        "fact": {
          "content": "Madrid is the capital city of Spain."
        },
        "entailment": "contradicted"
      }
    ]
  },
  "usage": {
    "prompt_tokens": 1223,
    "completion_tokens": 51,
    "total_tokens": 1274
  }
}
```


# Evaluation overview
Source: https://docs.pinecone.io/guides/assistant/evaluation-overview

Overview of Pinecone Assistant response evaluation: measure correctness, completeness, and alignment scores to benchmark RAG system quality.

You can [evaluate the correctness and completeness of a response](/guides/assistant/evaluate-answers) from an assistant or RAG system.

## Use cases

Response evaluation is useful when performing tasks like the following:

* Understanding how well the Pinecone Assistant captures the facts of the ground truth answer.
* Comparing the Pinecone Assistant's answers to those of another RAG system.
* Comparing the answers of your own RAG system to those of the Pinecone Assistant or another RAG system.

## SDK support

You can [evaluate responses](/reference/api/latest/assistant/metrics_alignment) directly or through the [Pinecone Python SDK](/reference/sdks/python/overview).

## Request

The request body requires the following fields:

| Field                 | Description                                           |
| --------------------- | ----------------------------------------------------- |
| `question`            | The question asked to the RAG system.                 |
| `answer`              | The answer provided by the assistant being evaluated. |
| `ground_truth_answer` | The expected answer.                                  |

For example:

```json theme={null}
{
  "question": "What are the capital cities of France, England and Spain?",
  "answer": "Paris is the capital city of France and Barcelona of Spain",
  "ground_truth_answer": "Paris is the capital city of France, London of England and Madrid of Spain."
}
```

## Response

### Metrics

Calculated scores between `0` to `1` are returned for the following metrics:

| Metric         | Description                                                                  |
| -------------- | ---------------------------------------------------------------------------- |
| `correctness`  | Correctness of the RAG system's answer compared to the ground truth answer.  |
| `completeness` | Completeness of the RAG system's answer compared to the ground truth answer. |
| `alignment`    | A combined score of the correctness and completeness scores.                 |

```json theme={null}
{
  "metrics": {
    "correctness": 0.5,
    "completeness": 0.333,
    "alignment": 0.398,
  }
},

...
```

### Reasoning

The response includes explanations for the reasoning behind each metric's score. This includes a list of evaluated facts with their entailment status:

| Status         | Description                                                                |
| -------------- | -------------------------------------------------------------------------- |
| `entailed`     | The fact is supported by the ground truth answer.                          |
| `contradicted` | The fact contradicts the ground truth answer.                              |
| `neutral`      | The fact is neither supported nor contradicted by the ground truth answer. |

```json theme={null}
...

  "reasoning":{
    "evaluated_facts": [
      {
        "fact": {"content": "Paris is the capital of France"},
        "entailment": "entailed",
      },
      {
        "fact": {"content": "London is the capital of England"},
        "entailment": "neutral"
      },
      {
        "fact": {"content": "Madrid is the capital of Spain"},
        "entailment": "contradicted",
      }
    ]
  },

...
```

### Usage

The response includes the number of tokens used to calculate the metrics. This includes the number of tokens used for the prompt and completion.

```json theme={null}
...

  "usage": {
    "prompt_tokens": 22,
    "completion_tokens": 33,
    "total_tokens": 55
  }
}
```

## Pricing

Cost is calculated by [token usage](#usage). See [Pricing](https://www.pinecone.io/pricing/) for up-to-date pricing information.

Response evaluation is only available for [Standard and Enterprise plans](https://www.pinecone.io/pricing/).


# Files in Pinecone Assistant
Source: https://docs.pinecone.io/guides/assistant/files-overview

Overview of Pinecone Assistant files: supported file types (PDF, DOCX, JSON, MD, TXT), metadata filters, storage, and signed URL access.

Before you can chat with the assistant, you need to [upload files](/guides/assistant/manage-files#upload-a-local-file). The files provide your assistant with context and information to reference when generating responses. Files are not shared across assistants.

### Supported file types

Pinecone Assistant supports the following file types:

* DOCX (.docx)
* JSON (.json)
* Markdown (.md)
* PDF (.pdf)
* Text (.txt)

<Note>
  For PDF files, assistants support [multimodal context](/guides/assistant/multimodal), allowing them to analyze and gather context from images. This feature is in [public preview](/release-notes/feature-availability).
</Note>

For information about file size and storage limits, see [Pricing and limits](/guides/assistant/pricing-and-limits).

### File storage

Files are uploaded to Google Cloud Storage (`us-central1` region) and to your organization's Pinecone vector database. The assistant processes the files, so data is not sent outside of blob storage or Pinecone.

Some API responses include a `signed_url` field, which provides temporary, read-only access to one of the assistant's files. The URL is [signed](https://cloud.google.com/storage/docs/access-control/signed-urls) and hard to guess, but publicly accessible, so treat it as sensitive. `signed_url` links expire in one hour.

### File identifiers

Each file in an assistant has a unique identifier. File IDs can be:

* **System-generated**: When you [upload a file](/guides/assistant/upload-files#upload-a-local-file) using `POST`, the system assigns a UUID as the file ID.
* **User-provided**: When you [upsert a file](/guides/assistant/upload-files#upsert-a-file) using `PUT`, you provide a custom file ID. User-provided IDs must be 1-128 characters long and can contain alphanumeric characters, hyphens, and underscores. Requires [API version](/reference/api/versioning) `2026-04` or later.

### File metadata

You can [upload a file with metadata](/guides/assistant/upload-files#upload-a-file-with-metadata), which allows you to store additional information about the file as key-value pairs.

<Warning>
  File metadata can be set only when the file is uploaded. You cannot update metadata after the file is uploaded.
</Warning>

File metadata can be used for the following purposes:

* [Filtering chat responses](/guides/assistant/chat-with-assistant#filter-chat-with-metadata): Specify filters on assistant responses so only files that match the metadata filter are referenced in the response. Chat requests without metadata filters do not consider metadata.
* [Viewing a filtered list of files](/guides/assistant/manage-files#view-a-filtered-list-of-files): Use metadata filters to list files in an assistant that match specific criteria.

#### Supported metadata size and format

Pinecone Assistant supports 16 KB of metadata per file.

* Metadata fields must be key-value pairs in a flat JSON object. Nested JSON objects are not supported.
* Keys must be strings and must not start with a `$`.
* Values must be one of the following data types:
  * String
  * Integer (converted to a 64-bit floating point by Pinecone)
  * Floating point
  * Boolean (`true`, `false`)
  * List of strings
* Null metadata values aren't supported. Instead of setting a key to `null`, remove the key from the metadata payload.

**Examples**

<CodeGroup>
  ```json Valid metadata theme={null}
  {
    "document_id": "document1",
    "document_title": "Introduction to Vector Databases",
    "chunk_number": 1,
    "chunk_text": "First chunk of the document content...",
    "is_public": true,
    "tags": ["beginner", "database", "vector-db"],
    "scores": ["85", "92"]
  }
  ```

  ```json Invalid metadata theme={null}
  {
    "document": {       // Nested JSON objects are not supported
      "document_id": "document1",
      "document_title": "Introduction to Vector Databases",
    },
    "$chunk_number": 1, // Keys must not start with a `$`
    "chunk_text": null, // Null values are not supported
    "is_public": true,
    "tags": ["beginner", "database", "vector-db"],
    "scores": [85, 92]  // Lists of non-strings are not supported
  }
  ```
</CodeGroup>

#### Metadata query language

Pinecone's filtering language supports the following operators:

| Operator  | Function                                                                                                                   | Supported types         |
| :-------- | :------------------------------------------------------------------------------------------------------------------------- | :---------------------- |
| `$eq`     | Matches  with metadata values that are equal to a specified value. Example: `{"genre": {"$eq": "documentary"}}`            | Number, string, boolean |
| `$ne`     | Matches  with metadata values that are not equal to a specified value. Example: `{"genre": {"$ne": "drama"}}`              | Number, string, boolean |
| `$gt`     | Matches  with metadata values that are greater than a specified value. Example: `{"year": {"$gt": 2019}}`                  | Number                  |
| `$gte`    | Matches  with metadata values that are greater than or equal to a specified value. Example:`{"year": {"$gte": 2020}}`      | Number                  |
| `$lt`     | Matches  with metadata values that are less than a specified value. Example: `{"year": {"$lt": 2020}}`                     | Number                  |
| `$lte`    | Matches  with metadata values that are less than or equal to a specified value. Example: `{"year": {"$lte": 2020}}`        | Number                  |
| `$in`     | Matches  with metadata values that are in a specified array. Example: `{"genre": {"$in": ["comedy", "documentary"]}}`      | String, number          |
| `$nin`    | Matches  with metadata values that are not in a specified array. Example: `{"genre": {"$nin": ["comedy", "documentary"]}}` | String, number          |
| `$exists` | Matches  with the specified metadata field. Example: `{"genre": {"$exists": true}}`                                        | Number, string, boolean |
| `$and`    | Joins query clauses with a logical `AND`. Example: `{"$and": [{"genre": {"$eq": "drama"}}, {"year": {"$gte": 2020}}]}`     | -                       |
| `$or`     | Joins query clauses with a logical `OR`. Example: `{"$or": [{"genre": {"$eq": "drama"}}, {"year": {"$gte": 2020}}]}`       | -                       |

<Note>
  Only `$and` and `$or` are allowed at the top level of the query expression.
</Note>

<Note>
  Each `$in` or `$nin` operator accepts a maximum of 10,000 values. Exceeding this limit will cause the request to fail. For more information, see [Metadata filter limits](/reference/api/database-limits#metadata-filter-limits).
</Note>

For example, the following has a `"genre"` metadata field with a list of strings:

```JSON JSON theme={null}
{ "genre": ["comedy", "documentary"] }
```

This means `"genre"` takes on both values, and requests with the following filters will match:

```JSON JSON theme={null}
{"genre":"comedy"}

{"genre": {"$in":["documentary","action"]}}

{"$and": [{"genre": "comedy"}, {"genre":"documentary"}]}
```

However, requests with the following filter will **not** match:

```JSON JSON theme={null}
{ "$and": [{ "genre": "comedy" }, { "genre": "drama" }] }
```

Additionally, requests with the following filters will **not** match because they are invalid. They will result in a compilation error:

```json JSON theme={null}
# INVALID QUERY:
{"genre": ["comedy", "documentary"]}
```

```json JSON theme={null}
# INVALID QUERY:
{"genre": {"$eq": ["comedy", "documentary"]}}
```


# Manage assistants
Source: https://docs.pinecone.io/guides/assistant/manage-assistants

List, describe, update, and delete Pinecone assistants and check assistant status using the API, Python SDK, Node.js SDK, or Pinecone console.

## List assistants for a project

You can [get the name, status, and metadata for each assistant](/reference/api/latest/assistant/list_assistants) in your project as in the following example:

<CodeGroup>
  ```python Python theme={null}
  # To use the Python SDK, install the plugin:
  # pip install --upgrade pinecone pinecone-plugin-assistant

  from pinecone import Pinecone
  pc = Pinecone(api_key="YOUR_API_KEY")

  assistants = pc.assistant.list_assistants()
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone';

  const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' });

  const assistants = await pc.listAssistants();
  console.log(assistants);
  ```

  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"

  curl -X GET "https://api.pinecone.io/assistant/assistants" \
    -H "Api-Key: $PINECONE_API_KEY"
  ```
</CodeGroup>

This operation returns a response like the following:

```JSON theme={null}
{
  "assistants": [
    {
      "name": "example-assistant",
      "instructions": "Use American English for spelling and grammar.",
      "metadata": {"team": "customer-support", "version": "1.0"},
      "status": "Initializing",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z"
    }
  ]
}
```

You can use the `name` value to [check the status of an assistant](/guides/assistant/manage-assistants#get-the-status-of-an-assistant).

<Tip>
  You can list assistants using the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/assistant/-/files).
</Tip>

## Get the status of an assistant

You can [get the status and metadata for your assistant](/reference/api/latest/assistant/describe_assistant) as in the following example:

<CodeGroup>
  ```python Python theme={null}
  # To use the Python SDK, install the plugin:
  # pip install --upgrade pinecone pinecone-plugin-assistant

  from pinecone import Pinecone
  pc = Pinecone(api_key="YOUR_API_KEY")

  assistant = pc.assistant.describe_assistant(
      assistant_name="example-assistant", 
  )
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone';

  const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' });

  const assistant = await pc.describeAssistant('example-assistant');
  console.log(assistant);
  ```

  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  ASSISTANT_NAME="example-assistant"

  curl -X GET "https://api.pinecone.io/assistant/assistants/$ASSISTANT_NAME" \
    -H "Api-Key: $PINECONE_API_KEY"
  ```
</CodeGroup>

This operation returns a response like the following:

```JSON theme={null}
{
  "name": "example-assistant",
  "instructions": "Use American English for spelling and grammar.",
  "metadata": {"team": "customer-support", "version": "1.0"},
  "status": "Initializing",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z"
}
```

The `status` field has the following possible values:

* Initializing
* Failed
* Ready
* Terminating

<Tip>
  You can check the status of an assistant using the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/assistant).
</Tip>

## Change an assistant's chat model

The chat model is the underlying large language model (LLM) that powers the assistant's responses. You can change the chat model for an existing assistant through the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/assistant):

1. On the **Assistants** page, select the assistant you want to update.
2. In the sidebar on the right, select **Settings** (gear icon).
3. Select the **Chat model**.

## Add instructions to an assistant

You can [add or update the instructions](/reference/api/latest/assistant/update_assistant) for an existing assistant. Instructions are a short description or directive for the assistant to apply to all of its responses. For example, you can update the instructions to reflect the assistant's role or purpose.

<Note>
  Instructions (maximum size 16 KB) are included in every chat API call. Longer instructions increase input token costs for each request and consume more of the LLM's context window, reducing available space for retrieved context and conversation history.
</Note>

For example:

<CodeGroup>
  ```python Python theme={null}
  # To use the Python SDK, install the plugin:
  # pip install --upgrade pinecone pinecone-plugin-assistant

  from pinecone import Pinecone

  pc = Pinecone(api_key=YOUR_API_KEY)

  assistant = pc.assistant.update_assistant(
      assistant_name="example-assistant", 
      instructions="Use American English for spelling and grammar.",
      metadata={"team": "customer-support", "version": "1.1"} # Optional metadata (max 16KB) for organizing assistants.
  )
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone';

  const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' });

  await pc.updateAssistant('example-assistant', {
    instructions: 'Use American English for spelling and grammar.',
    metadata: { team: 'customer-support', version: '1.1' }, // Optional metadata (max 16KB) for organizing assistants.
  });
  ```

  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"

  curl -X PATCH "https://api.pinecone.io/assistant/assistants/example-assistant" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "instructions": "Use American English for spelling and grammar.",
    "metadata": {"team": "customer-support", "version": "1.1"}
  }'
  ```
</CodeGroup>

The example above returns a result like the following:

```JSON theme={null}
{
    "name":"example-assistant",
    "instructions":"Use American English for spelling and grammar.",
    "metadata":{"team": "customer-support", "version": "1.1"},
    "status":"Ready",
    "created_at":"2024-06-14T14:58:06.573004549Z",
    "updated_at":"2024-10-01T19:44:32.813235817Z"
}
```

<Tip>
  You can add or update instructions for an assistant using the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/assistant).
</Tip>

## Delete an assistant

You can [delete an assistant](/reference/api/latest/assistant/delete_assistant) as in the following example:

<Warning>
  Deleting an assistant also deletes all files uploaded to the assistant.
</Warning>

<CodeGroup>
  ```python Python theme={null}
  # To use the Python SDK, install the plugin:
  # pip install --upgrade pinecone pinecone-plugin-assistant

  from pinecone import Pinecone
  pc = Pinecone(api_key="YOUR_API_KEY")

  pc.assistant.delete_assistant(
      assistant_name="example-assistant", 
  )
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone';

  const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' });

  await pc.deleteAssistant('example-assistant');
  ```

  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  ASSISTANT_NAME="example-assistant"

  curl -X DELETE "https://api.pinecone.io/assistant/assistants/$ASSISTANT_NAME" \
    -H "Api-Key: $PINECONE_API_KEY"
  ```
</CodeGroup>

<Tip>
  You can delete an assistant using the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/assistant).
</Tip>


# Manage files
Source: https://docs.pinecone.io/guides/assistant/manage-files

List files in your Pinecone assistant, check individual file ingestion status by ID, view metadata, and delete files using the API, SDKs, or console.

<Note>
  File upload limitations depend on the plan you are using. For more information, see [Pricing and limitations](/guides/assistant/pricing-and-limits#limits).
</Note>

## List files in an assistant

### View all files

You can [get the status, ID, and metadata for each file in your assistant](/reference/api/latest/assistant/list_files), as in the following example:

<CodeGroup>
  ```python Python theme={null}
  # To use the Python SDK, install the plugin:
  # pip install --upgrade pinecone pinecone-plugin-assistant

  from pinecone import Pinecone
  pc = Pinecone(api_key="YOUR_API_KEY")

  # Get your assistant.
  assistant = pc.assistant.Assistant(
      assistant_name="example-assistant", 
  )

  # List files in your assistant.
  files = assistant.list_files()
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone'

  const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' });

  const assistantName = 'example-assistant';
  const assistant = pc.Assistant(assistantName);
  const files = await assistant.listFiles();
  console.log(files);
  ```

  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  ASSISTANT_NAME="example-assistant"

  curl -X GET "https://prod-1-data.ke.pinecone.io/assistant/files/$ASSISTANT_NAME" \
    -H "Api-Key: $PINECONE_API_KEY"
  ```
</CodeGroup>

This operation returns a response like the following:

```JSON theme={null}
{
  "files": [
    {
      "status": "Available",
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "example_file.txt",
      "size": 1073470,
      "metadata": {},
      "updated_on": "2025-07-16T16:46:40.787204651Z",
      "created_on": "2025-07-16T16:45:59.414273474Z",
      "signed_url": null
    }
  ]
}
```

You can use the `id` value to [check the status of an individual file](#get-the-status-of-a-file).

<Tip>
  You can list file in an assistant using the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/assistant). Select the assistant and view the files in the Assistant playground.
</Tip>

### View a filtered list of files

Metadata filter expressions can be included when listing files. This will limit the list of files to only those matching the filter expression. Use the `filter` parameter to specify the metadata filter expression.

For more information about filtering with metadata, see [Understanding files](/guides/assistant/files-overview#metadata-query-language).

The following example lists files that are a manuscript:

<CodeGroup>
  ```Python Python theme={null}
  # To use the Python SDK, install the plugin:
  # pip install --upgrade pinecone pinecone-plugin-assistant

  from pinecone import Pinecone
  pc = Pinecone(api_key="YOUR_API_KEY")

  # Get your assistant.
  assistant = pc.assistant.Assistant(
      assistant_name="example-assistant", 
  )

  # List files in your assistant that match the metadata filter.
  files = assistant.list_files(filter={"document_type":"manuscript"})
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone'

  const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' });

  const assistantName = 'example-assistant';
  const assistant = pc.Assistant(assistantName);
  const files = await assistant.listFiles({
    filter: { document_type: 'manuscript' },
  });
  console.log(files);

  // You can also use filter operators:
  // const files = await assistant.listFiles({
  //   filter: { document_type: { '$ne': 'manuscript' } },
  // });
  ```

  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  ASSISTANT_NAME="example-assistant"
  ENCODED_METADATA="%7B%22document_type%22%3A%20%22manuscript%22%7D" # URL encoded metadata - See w3schools.com/tags/ref_urlencode.ASP

  curl -X GET "https://prod-1-data.ke.pinecone.io/assistant/files/$ASSISTANT_NAME?filter=$ENCODED_METADATA" \
    -H "Api-Key: $PINECONE_API_KEY"
  ```
</CodeGroup>

## Get the status of a file

You can [get the status and metadata for your assistant](/reference/api/latest/assistant/describe_file), as in the following example:

<CodeGroup>
  ```python Python theme={null}
  # To use the Python SDK, install the plugin:
  # pip install --upgrade pinecone pinecone-plugin-assistant

  from pinecone import Pinecone
  pc = Pinecone(api_key="YOUR_API_KEY")

  # Get an assistant.
  assistant = pc.assistant.Assistant(
      assistant_name="example-assistant", 
  )

  # Describe a file. 
  # To get a signed URL in the response, set `include_url` to `True`.
  file = assistant.describe_file(file_id="3c90c3cc-0d44-4b50-8888-8dd25736052a", include_url=True)
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone'

  const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' });

  const assistantName = 'example-assistant';
  const assistant = pc.Assistant(assistantName);
  const fileId = "3c90c3cc-0d44-4b50-8888-8dd25736052a";

  // Describe a file. Returns a signed URL by default. 
  const file = await assistant.describeFile(fileId)
  // To exclude signed URL, set `includeUrl` to `false`.
  // const includeUrl = false;
  // const file = await assistant.describeFile(fileId, includeUrl)
  ```

  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  ASSISTANT_NAME="example-assistant"
  FILE_ID="3c90c3cc-0d44-4b50-8888-8dd25736052a"

  # Describe a file. 
  # To get a signed URL in the response, set `include_url` to `true`.
  curl -X GET "https://prod-1-data.ke.pinecone.io/assistant/files/$ASSISTANT_NAME/$FILE_ID?include_url=true" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2026-04"
  ```
</CodeGroup>

This operation returns a response like the following:

```JSON theme={null}
{
  "status": "Available",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "example_file.txt",
  "size": 1073470,
  "metadata": {},
  "updated_on": "2025-07-16T16:46:40.787204651Z",
  "created_on": "2025-07-16T16:45:59.414273474Z",
  "signed_url": "https://storage.googleapis.com/..."
}
```

<Warning>
  [`signed_url`](https://cloud.google.com/storage/docs/access-control/signed-urls) provides temporary, read-only access to the relevant file. Anyone with the link can access the file, so treat it as sensitive data. Expires in one hour.
</Warning>

<Tip>
  You can check the status a file using the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/assistant). In the Assistant playground, click the file for more details.
</Tip>

## Track file operations

<Note>
  This feature requires [API version](/reference/api/versioning) `2026-04` or later.
</Note>

File uploads, upserts, and deletes are asynchronous. Each action returns an **operation** object that you can poll for status and progress.

Use [List operations](/reference/api/2026-04/assistant/list_operations) and [Describe an operation](/reference/api/2026-04/assistant/describe_operation) for the HTTP API. Example requests:

<CodeGroup>
  ```bash List operations theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  ASSISTANT_NAME="example-assistant"

  curl -X GET "https://prod-1-data.ke.pinecone.io/assistant/operations/$ASSISTANT_NAME" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2026-04"
  ```

  ```bash Describe operation theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  ASSISTANT_NAME="example-assistant"
  OPERATION_ID="op-1234-abcd-5678"

  curl -X GET "https://prod-1-data.ke.pinecone.io/assistant/operations/$ASSISTANT_NAME/$OPERATION_ID" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2026-04"
  ```
</CodeGroup>

Operation status values include **Processing** (use `percent_complete` for progress), **Completed**, and **Failed** (the response may include `error_message`). The `percent_complete` field on operations replaces `percent_done` on the file model; ingestion usage for completed file work may appear as **`ingestion_units`** on the operation.

## Delete a file

You can [delete a file](/reference/api/latest/assistant/delete_file) from an assistant.

<CodeGroup>
  ```python Python theme={null}
  # To use the Python SDK, install the plugin:
  # pip install --upgrade pinecone pinecone-plugin-assistant

  from pinecone import Pinecone
  pc = Pinecone(api_key="YOUR_API_KEY")

  # Get your assistant.
  assistant = pc.assistant.Assistant(
      assistant_name="example-assistant", 
  )

  # Delete a file from your assistant.
  assistant.delete_file(file_id="3c90c3cc-0d44-4b50-8888-8dd25736052a")
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone'

  const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' });

  const assistantName = 'example-assistant';
  const assistant = pc.Assistant(assistantName);

  const file = await assistant.deleteFile("070513b3-022f-4966-b583-a9b12e0290ff")
  ```

  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  ASSISTANT_NAME="example-assistant"
  FILE_ID="3c90c3cc-0d44-4b50-8888-8dd25736052a"

  curl -X DELETE "https://prod-1-data.ke.pinecone.io/assistant/files/$ASSISTANT_NAME/$FILE_ID" \
    -H "Api-Key: $PINECONE_API_KEY"
  ```
</CodeGroup>

* Once a file is deleted, you cannot recover it.
* With [API version](/reference/api/versioning) `2026-04` or later, delete is asynchronous and returns an operation ID. You can [track file operations](#track-file-operations) to monitor progress.
* You cannot delete a file while it is still processing.
* You can also delete a file from an assistant using the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/assistant). In the Assistant playground, find the file and click the **ellipsis (...) menu > Delete**.

## Track file operations

<Note>
  This feature requires [API version](/reference/api/versioning) `2026-04` or later.
</Note>

File uploads, upserts, and deletes are asynchronous operations. Each of these actions returns an operation object that you can poll for status and progress.

### List operations

You can [list all operations](/reference/api/2026-04/assistant/list_operations) for an assistant:

<CodeGroup>
  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  ASSISTANT_NAME="example-assistant"

  curl -X GET "https://prod-1-data.ke.pinecone.io/assistant/operations/$ASSISTANT_NAME" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2026-04"
  ```
</CodeGroup>

This returns a list of operations:

```JSON theme={null}
{
  "operations": [
    {
      "id": "op-1234-abcd-5678",
      "operation_type": "upload_file",
      "file_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "status": "Completed",
      "created_on": "2025-10-01T12:00:00Z",
      "completed_on": "2025-10-01T12:05:00Z",
      "percent_complete": 100
    },
    {
      "id": "op-8765-dcba-4321",
      "operation_type": "upsert_file",
      "file_id": "my-custom-file-id",
      "status": "Processing",
      "created_on": "2025-10-01T12:30:00Z",
      "percent_complete": 45
    }
  ]
}
```

### Describe an operation

You can [get the status of a specific operation](/reference/api/2026-04/assistant/describe_operation):

<CodeGroup>
  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  ASSISTANT_NAME="example-assistant"
  OPERATION_ID="op-1234-abcd-5678"

  curl -X GET "https://prod-1-data.ke.pinecone.io/assistant/operations/$ASSISTANT_NAME/$OPERATION_ID" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2026-04"
  ```
</CodeGroup>

```JSON theme={null}
{
  "id": "op-1234-abcd-5678",
  "operation_type": "upload_file",
  "file_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "Completed",
  "created_on": "2025-10-01T12:00:00Z",
  "completed_on": "2025-10-01T12:05:00Z",
  "percent_complete": 100
}
```

### Operation status values

Operations can have the following status values:

* **Processing**: The operation is in progress. Use `percent_complete` to track progress.
* **Completed**: The operation finished successfully.
* **Failed**: The operation failed. In this case, the operation response includes `error_message`.

<Note>
  The `percent_complete` field on operations replaces the `percent_done` field that was previously on the file model. Similarly, `error_message` appears on failed operations, not on the file model.
</Note>


# Use an Assistant MCP server
Source: https://docs.pinecone.io/guides/assistant/mcp-server

Connect AI agents to a Pinecone Assistant MCP server via remote or local Model Context Protocol endpoints, including Cursor and Claude Desktop.

Every Pinecone Assistant has a dedicated MCP server that gives AI agents direct access to context from the assistant's uploaded files through the standardized [Model Context Protocol (MCP)](https://modelcontextprotocol.io/). This page shows you how to connect an assistant's MCP server with Cursor, Claude Desktop, and LangChain.

<Note>
  Pinecone also provides an MCP server for managing indexes, upserting data, and querying your Pinecone database directly from an AI agent. See [Use the Pinecone MCP server](/guides/operations/mcp-server).
</Note>

There are two ways to connect to an assistant MCP server:

* [Remote MCP server](#remote-mcp-server) - Use a dedicated MCP endpoint to connect directly to an assistant.
* [Local MCP server](#local-mcp-server) - Run a Docker container locally that connects to an assistant

Both options support a context tool that allows agents to retrieve relevant context snippets from your assistant's uploaded files. This is similar to the [context API](/guides/assistant/retrieve-context-snippets) but fine-tuned for MCP clients. Additional capabilities, such as file access, will be added in future releases.

## Remote MCP server

Every Pinecone Assistant has a dedicated MCP endpoint that you can connect directly to your AI applications. This option doesn't require running any infrastructure and is managed by Pinecone.

The MCP endpoint for an assistant is:

```
https://<YOUR_PINECONE_ASSISTANT_HOST>/mcp/assistants/<YOUR_ASSISTANT_NAME>
```

<Warning>
  The previous SSE-based endpoint (with `/sse` suffix) is deprecated and will stop working on August 31, 2025 at 11:59:59 PM UTC. Before then, update to the [streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) MCP endpoint shown above, which implements the current MCP specification and provides improved flexibility and compatibility.
</Warning>

### Prerequisites

Before you begin, make sure you have the following values, which you'll use in the commands below:

* `<YOUR_PINECONE_API_KEY>`: [A Pinecone API key](/guides/projects/manage-api-keys).
* `<YOUR_PINECONE_ASSISTANT_HOST>`: In the Pinecone console, this is your assistant's **Host** value.
* `<YOUR_ASSISTANT_NAME>`: Your assistant's name, as displayed in the Pinecone console. For example, `example-assistant`.

### Use with Claude Code

You can use the Claude CLI to configure Claude Code to use your assistant's remote MCP server. For more information, see [Claude Code's MCP documentation](https://docs.anthropic.com/en/docs/claude-code/mcp).

1. Add the MCP server using the Claude CLI:

   ```bash theme={null}
   claude mcp add --transport http my-assistant https://<YOUR_PINECONE_ASSISTANT_HOST>/mcp/assistants/<YOUR_ASSISTANT_NAME> --header "Authorization: Bearer <YOUR_PINECONE_API_KEY>"
   ```

   Replace `<YOUR_PINECONE_API_KEY>` with your Pinecone API key, `<YOUR_PINECONE_ASSISTANT_HOST>` with your Pinecone Assistant host, and `<YOUR_ASSISTANT_NAME>` with your assistant's name.

2. Verify the server was added successfully:

   ```bash theme={null}
   claude mcp get my-assistant
   ```

3. The MCP server tools should now be available in Claude Code's chat interface.

### Use with Claude Desktop

You can configure Claude Desktop to use your assistant's remote MCP server. However, at this early stage of **remote** MCP server adoption, the Claude Desktop application does not support remote server URLs. In the example below, we work around this by using a local proxy server, [supergateway](https://github.com/supercorp-ai/supergateway), to forward requests to the remote MCP server with your API key.

<Warning>
  [supergateway](https://github.com/supercorp-ai/supergateway) is an open-source third-party tool. Use at your own risk.
</Warning>

1. Open [Claude Desktop](https://claude.ai/download) and go to **Settings**.

2. On the **Developer** tab, click **Edit Config** to open the configuration file.

3. Add the following configuration:

   ```json theme={null}
   {
     "mcpServers": {
       "Assistant over supergateway": {
         "command": "npx",
         "args": [
           "-y",
           "supergateway",
           "--streamableHttp",
           "https://<YOUR_PINECONE_ASSISTANT_HOST>/mcp/assistants/<YOUR_ASSISTANT_NAME>",
           "--header",
           "Authorization: Bearer <YOUR_PINECONE_API_KEY>"
         ]
       }
     }
   }
   ```

   Replace `<YOUR_PINECONE_API_KEY>` with your Pinecone API key and `<YOUR_PINECONE_ASSISTANT_HOST>` with your Pinecone Assistant host.

4. Save the configuration file and restart Claude Desktop.

5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available.

### Use with Cursor

You can configure Cursor to use your assistant's remote MCP server directly through the `.cursor/mcp.json` configuration file.

1. Open [Cursor](https://www.cursor.com/) and create a `.cursor` directory in your project root if it doesn't exist.

2. Open `.cursor/mcp.json` (create it if necessary). To learn more, refer to [Cursor's MCP documentation](https://docs.cursor.com/context/mcp).

3. Add the following configuration:

   ```json theme={null}
   {
     "mcpServers": {
       "pinecone-assistant": {
         "url": "https://<YOUR_PINECONE_ASSISTANT_HOST>/mcp/assistants/<YOUR_ASSISTANT_NAME>",
         "headers": {
           "Authorization": "Bearer <YOUR_PINECONE_API_KEY>"
         }
       }
     }
   }
   ```

   Replace `<YOUR_PINECONE_API_KEY>` with your Pinecone API key, `<YOUR_PINECONE_ASSISTANT_HOST>` with your Pinecone Assistant host, and `<YOUR_ASSISTANT_NAME>` with your assistant's name.

4. Save the configuration file.

5. The MCP server tools should now be available in Cursor's chat interface.

### Use with LangChain

You can use the [LangChain MCP client](https://github.com/langchain-ai/langchain-mcp-adapters) to integrate with LangChain to create a powerful multi-agent workflow.

For example, the following code integrates Langchain with two assistants, one called `ai-news` and the other called `industry-reports`:

```python Python theme={null}
# Example code for integrating with LangChain
from langchain_mcp_adapters.client import MultiServerMCPClient
from langgraph.prebuilt import create_react_agent

from langchain_anthropic import ChatAnthropic

model = ChatAnthropic(model_name="claude-3-7-sonnet-latest", api_key="YOUR_ANTHROPIC_API_KEY")
pinecone_api_key = "<YOUR_PINECONE_API_KEY>"

async with MultiServerMCPClient(
    {
        "assistant_ai_news": {
            "url": "https://prod-1-data.ke.pinecone.io/mcp/assistants/ai-news",
            "transport": "streamable_http",
            "headers": {
                "Authorization": f"Bearer {pinecone_api_key}"
            }
        },
        "assistant_industry_reports": {
            "url": "https://prod-1-data.ke.pinecone.io/mcp/assistants/industry-reports",
            "transport": "streamable_http",
            "headers": {
                "Authorization": f"Bearer {pinecone_api_key}"
            }
        }
    }
) as client:
    agent = create_react_agent(model, client.get_tools())

    response = await agent.ainvoke({"messages": "Your task is research the next trends in AI, and form a report with the most undervalued companies in the space. You have access to two assistants, one that can help you find the latest trends in AI, and one that can help you find reports on companies."})
    print(response["messages"][-1].content)
```

## Local MCP server

Pinecone provides an open-source Pinecone Assistant MCP server that you can run locally with Docker. This option is useful for development, testing, or when you want to run the MCP server within your own infrastructure or expand the MCP server to include additional capabilities.

For the most up-to-date information on the local MCP server, see the [Pinecone Assistant MCP server repository](https://github.com/pinecone-io/assistant-mcp).

### Prerequisites

* Docker is installed and running on your system.
* A Pinecone API key. You can create a new key in the [Pinecone console](https://app.pinecone.io/organizations/-/keys).
* Your Pinecone Assistant host. To find it, go to your assistant in the [Pinecone console](https://app.pinecone.io/organizations/-/assistants). You'll see the assistant **Host** in the sidebar.

### Start the MCP server

Download the `assistant-mcp` Docker image:

```bash theme={null}
docker pull ghcr.io/pinecone-io/assistant-mcp
```

Start the MCP server, providing your Pinecone API key and Pinecone Assistant host:

```bash theme={null}
docker run -i --rm \
  -e PINECONE_API_KEY=<PINECONE_API_KEY> \
  -e PINECONE_ASSISTANT_HOST=<PINECONE_ASSISTANT_HOST> \
  pinecone/assistant-mcp
```

### Use with Claude Desktop

1. Open [Claude Desktop](https://claude.ai/download) and go to **Settings**.

2. On the **Developer** tab, click **Edit Config** to open the configuration file.

3. Add the following configuration:

   ```json theme={null}
   {
     "mcpServers": {
       "pinecone-assistant": {
         "command": "docker",
         "args": [
           "run", 
           "-i", 
           "--rm", 
           "-e", 
           "PINECONE_API_KEY", 
           "-e", 
           "PINECONE_ASSISTANT_HOST", 
           "pinecone/assistant-mcp"
         ],
         "env": {
           "PINECONE_API_KEY": "<YOUR_PINECONE_API_KEY>",
           "PINECONE_ASSISTANT_HOST": "<YOUR_PINECONE_ASSISTANT_HOST>"
         }
       }
     }
   }
   ```

   Replace `<YOUR_PINECONE_API_KEY>` with your Pinecone API key and `<YOUR_PINECONE_ASSISTANT_HOST>` with your Pinecone Assistant host.

4. Save the configuration file and restart Claude Desktop.

5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available.

### Use with Cursor

1. Open [Cursor](https://www.cursor.com/) and create a `.cursor` directory in your project root if it doesn't exist.

2. Open `.cursor/mcp.json` (create it if necessary). To learn more, refer to [Cursor's MCP documentation](https://docs.cursor.com/context/mcp).

3. Add the following configuration:

   ```json theme={null}
   {
     "mcpServers": {
       "pinecone-assistant": {
         "command": "docker",
         "args": [
           "run", 
           "-i", 
           "--rm", 
           "-e", 
           "PINECONE_API_KEY", 
           "-e", 
           "PINECONE_ASSISTANT_HOST", 
           "pinecone/assistant-mcp"
         ],
         "env": {
           "PINECONE_API_KEY": "<YOUR_PINECONE_API_KEY>",
           "PINECONE_ASSISTANT_HOST": "<YOUR_PINECONE_ASSISTANT_HOST>"
         }
       }
     }
   }
   ```

   Replace `<YOUR_PINECONE_API_KEY>` with your Pinecone API key and `<YOUR_PINECONE_ASSISTANT_HOST>` with your Pinecone Assistant host.

4. Save the configuration file.

## Next Steps

* Visit the [Pinecone Assistant MCP Server repository](https://github.com/pinecone-io/assistant-mcp) for detailed installation and usage instructions

* Learn about [Model Context Protocol](https://modelcontextprotocol.io/) and how it enables AI agents to interact with tools and data

* Explore [retrieve context snippets](/guides/assistant/retrieve-context-snippets) to understand the underlying API functionality


# Multimodal context for assistants
Source: https://docs.pinecone.io/guides/assistant/multimodal

Enable multimodal PDF context in Pinecone Assistant to analyze charts, images, and diagrams using OCR and visual understanding for RAG.

<Note>
  This feature is in [public preview](/release-notes/feature-availability).
</Note>

Pinecone assistants support multimodal context, allowing them to understand and respond to questions about images embedded in PDF documents.

This enables use cases like:

* Analyzing charts, graphs, and diagrams in financial reports
* Understanding infographics and visual data in research papers
* Interpreting visual layouts in technical documentation

When working with multimodal PDFs, assistants attempt to filter out purely decorative images (such as example logos, background graphics, generic stock photos), so they can focus on images that contain meaningful information.

Additionally, assistants use Optical Character Recognition (OCR) to extract text from images. This allows them to read and analyze scanned PDFs (PDFs that contain images of text, but no actual embedded text).

## How it works

When you enable multimodal context for a PDF:

1. Pinecone extracts text and images (raster or vector) from the file and analyzes their contents. For each image, the assistant generates a descriptive caption and set of keywords. Additionally, when it makes sense, the assistant captures data points found in the image (for example, values from a table or chart).
2. During chat or context queries, the assistant searches for relevant text and image context it captured when analyzing the PDF. Image context can include the original image data (base64-encoded).
3. The assistant passes this context to the LLM, which uses it to generate responses.

<Note>
  For an overview of how Pinecone Assistant works, see [Pinecone Assistant architecture](/reference/architecture/assistant-architecture).
</Note>

## Try it out

The following steps demonstrate how to create an assistant, provide it with a PDF that contains images, and then query that assistant using chat and context APIs.

<Note>
  All versions of Pinecone's Assistant API allow you to upload multimodal PDFs.
</Note>

### 1. Create an assistant

First, if you don't have one, [create an assistant](/reference/api/2025-10/assistant/create_assistant):

<CodeGroup>
  ```Python Python theme={null}
  from pprint import pprint
  from pinecone import Pinecone

  pc = Pinecone("YOUR_API_KEY") 
  assistant = pc.assistant.create_assistant(
      assistant_name="example-assistant-multimodal", 
      instructions="You are a helpful assistant that can understand both text and images in documents.",
      region="us",
      timeout=30
  )

  print(f"Type: {type(assistant).__name__}")
  pprint(assistant)
  ```

  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"

  curl "https://api.pinecone.io/assistant/assistants" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
          "name": "example-assistant-multimodal",
          "instructions": "You are a helpful assistant that can understand both text and images in documents.",
          "region": "us"
        }'
  ```
</CodeGroup>

Response:

<CodeGroup>
  ```shell Python theme={null}
  Type: AssistantModel
  {'created_at': '2025-08-28T23:35:26.917953498Z',
    'host': 'https://prod-1-data.ke.pinecone.io',
    'instructions': 'You are a helpful assistant that can understand both text '
                    'and images in documents.',
    'metadata': {},
    'name': 'example-assistant-multimodal',
    'status': 'Ready',
    'updated_at': '2025-08-28T23:35:28.507639215Z'}
  ```

  ```json curl theme={null}
  {
    "name": "example-assistant-multimodal",
    "instructions": "You are a helpful assistant that can understand both text and images in documents.",
    "metadata": null,
    "status": "Initializing",
    "host": "https://prod-1-data.ke.pinecone.io",
    "created_at": "2025-08-18T23:18:52.858197495Z",
    "updated_at": "2025-08-18T23:18:52.858198077Z"
  }
  ```
</CodeGroup>

<Note>
  You don't need to create a new assistant to use multimodal context. Existing assistants can enable multimodal context for newly uploaded PDFs, as described in [the next section](#2-upload-a-multimodal-pdf).
</Note>

### 2. Upload a multimodal PDF

To enable multimodal context for a PDF, when [uploading the file](/reference/api/2025-10/assistant/upload_file), set the `multimodal` URL parameter to true (defaults to false).

<Tip>
  To improve retrieval accuracy for images found in uploaded PDFs, include relevant contextual text on the same page as each image. For example:

  * **Graphs and charts**: Include nearby text explaining the experiment, methodology, or data being visualized.
  * **Diagrams**: Add descriptive labels or explanations adjacent to technical diagrams.
  * **Tables**: Provide context about what the data represents and any relevant methodology.

  The assistant uses surrounding text when generating captions that are later passed to the LLM, so placing relevant context near images improves caption quality and retrieval accuracy.
</Tip>

<CodeGroup>
  ```Python Python theme={null}
  from pprint import pprint
  from pinecone import Pinecone

  pc = Pinecone("YOUR_API_KEY") 
  assistant = pc.assistant.Assistant(assistant_name="example-assistant-multimodal")

  # timeout=None allows the SDK to wait for file processing to complete before returning.
  # This parameter is only available in the SDK, not in direct API calls.
  file_model = assistant.upload_file(
      file_path="./document.pdf",
      multimodal=True,
      timeout=None
  )

  pprint(file_model)
  ```

  ```bash curl theme={null}
  ASSISTANT_HOST="YOUR_ASSISTANT_HOST"
  ASSISTANT_NAME="example-assistant-multimodal"
  PINECONE_API_KEY="YOUR_API_KEY"
  LOCAL_FILE_PATH="/path/to/your/document.pdf"

  curl -X POST "https://$ASSISTANT_HOST/assistant/files/$ASSISTANT_NAME?multimodal=true" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -F "file=@$LOCAL_FILE_PATH"
  ```
</CodeGroup>

Response:

<CodeGroup>
  ```shell Python theme={null}
  # Formatted for readability
  FileModel(
    name='document.pdf',
    id='9c322597-58d6-4ebc-84b5-a398b620da01',
    metadata=None,
    created_on='2025-08-28T23:41:41.982805815Z',
    updated_on='2025-08-28T23:42:09.562949544Z',
    status='Available',
    signed_url=None,
    size=1236044.0
  )
  ```

  ```json curl theme={null}
  {
    "id": "op-1234-abcd-5678",
    "operation_type": "upload_file",
    "file_id": "9c322597-58d6-4ebc-84b5-a398b620da01",
    "status": "Processing",
    "created_on": "2025-08-28T23:41:41.982805815Z",
    "percent_complete": 0
  }
  ```
</CodeGroup>

<Note>
  * The `multimodal` parameter is only available for PDF files.
  * Upload is asynchronous. To check the status, use the [describe operation](/reference/api/2026-04/assistant/describe_operation) endpoint or [track file operations](/guides/assistant/manage-files#track-file-operations).
  * If upload processing fails, you'll need to re-upload the file.
</Note>

### 3. Chat with the assistant

Now, [chat with your assistant](/reference/api/2025-10/assistant/chat_assistant). To tell the assistant to provide image-related context to the LLM:

* Set the `multimodal` request parameter to true (default) in the `context_options` object. Setting `multimodal` to false means the LLM only receives text snippets.
* When `multimodal` is true, use `include_binary_content` to specify what image context the LLM should receive: base64 image data and captions (true) or captions only (false).

<Note>
  Sending image-related context to the LLM (whether captions, base64 data, or both) increases token usage. Learn about [monitoring spend and usage](/guides/assistant/admin/monitor-spend-and-usage).
</Note>

<CodeGroup>
  ```Python Python theme={null}
  from pprint import pprint
  from pinecone import Pinecone
  from pinecone_plugins.assistant.models.chat import Message

  pc = Pinecone("YOUR_API_KEY") 
  assistant = pc.assistant.Assistant(assistant_name="example-assistant-multimodal")

  msg = Message(
      role="user", 
      content="Describe the symbol on the paper tray that indicates the maximum fill level."
  )

  chat_response = assistant.chat(
    messages=[msg],
    context_options={
        "multimodal": True,
        "include_binary_content": True,
        "top_k": 10,
        "snippet_size": 2048
    }
  )

  pprint(chat_response)
  ```

  ```bash curl theme={null}
  ASSISTANT_HOST="YOUR_ASSISTANT_HOST"
  ASSISTANT_NAME="example-assistant-multimodal"
  PINECONE_API_KEY="YOUR_API_KEY"

  curl "https://$ASSISTANT_HOST/assistant/chat/$ASSISTANT_NAME" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
          "messages": [
            {
              "role": "user",
              "content": "Describe the symbol on the paper tray that indicates the maximum fill level."
            }
          ],
          "context_options": {
            "multimodal": true,
            "include_binary_content": true,
            "top_k": 10,
            "snippet_size": 2048
          }
        }'
  ```
</CodeGroup>

Response:

<CodeGroup>
  ```shell Python theme={null}
  # Formatted for readability
  ChatResponse(
    id='00000000000000000fe49626f3ee5164', 
    model='gpt-4o-2024-11-20', 
    usage=Usage(
      prompt_tokens=8703, 
      completion_tokens=41, 
      total_tokens=8744
    ), 
    message=Message(
      content='The symbol on the paper tray that indicates...', 
      role='assistant'
    ), 
    finish_reason='stop', 
    citations=[
      Citation(
        position=209, 
        references=[
          Reference(
              file=FileModel(
                name='document.pdf', 
                id='9c322597-58d6-4ebc-84b5-a398b620da01', 
                metadata=None, 
                created_on='2025-08-28T23:41:41.982805815Z', 
                updated_on='2025-08-28T23:42:09.562949544Z', 
                status='Available', 
                signed_url='https://storage.googleapis.com/...',
                size=1236044.0,
                multimodal=True
            ), 
            pages=[3, 4, 5, 6, 7, 8, 9, 10, 11], 
            highlight=None
          )
        ]
      )
    ]
  )
  ```

  ```json curl theme={null}
  {
    "finish_reason": "stop",
    "message": {
      "role": "assistant",
      "content": "The symbol on the paper tray that indicates..."
    },
    "id": "0000000000000000d904dfd3dd4f4597"
    "model": "gpt-4o-2024-11-20",
    "usage": {
      "prompt_tokens": 8414,
      "completion_tokens": 42,
      "total_tokens": 8456
    },
    "citations": [
      {
        "position": 213,
        "references": [
          {
            "file": {
              "status": "Available",
              "id": "a89f678c-9ceb-40ec-8fc7-23913e560b37",
              "name": "document.pdf",
              "size": 1236044,
              "metadata": null,
              "multimodal": true,
              "updated_on": "2025-08-18T23:21:59.697988967Z",
              "created_on": "2025-08-18T23:21:36.498381046Z",
              "signed_url": "https://storage.googleapis.com/..."
            },
            "pages": [ 3, 4, 5, 6, 7, 8, 9, 10, 11 ],
            "highlight": null
          }
        ]
      }
    ]
  }
  ```
</CodeGroup>

<Warning>
  If your assistant uses multimodal context snippets to generate a response, no [highlights](/guides/assistant/chat-with-assistant#include-citation-highlights-in-the-response) are returned—even when `include_highlights` is true.
</Warning>

### 4. Query for context

To query context for a custom RAG workflow, you can [retrieve context snippets](/reference/api/2025-10/assistant/context_assistant) directly. Then, you can pass these snippets to an LLM as context.

To fetch image-related context snippets (as well as text snippets), set the `multimodal` request parameter to true (default). When `multimodal` is true, use `include_binary_content` to specify what image context you'd like to receive: base64 image data and captions (true) or captions only (false).

<CodeGroup>
  ```Python Python theme={null}
  from pprint import pprint
  from pinecone import Pinecone

  pc = Pinecone("PINECONE_API_KEY") 
  assistant = pc.assistant.Assistant(assistant_name="example-assistant-multimodal")
  context_response = assistant.context(
      query="Describe the symbol on the paper tray that indicates the maximum fill level.",
      multimodal=True,
      include_binary_content=True
  )

  pprint(context_response)
  ```

  ```bash curl theme={null}
  ASSISTANT_HOST="YOUR_ASSISTANT_HOST"
  ASSISTANT_NAME="example-assistant-multimodal"
  PINECONE_API_KEY="YOUR_API_KEY"

  curl "https://$ASSISTANT_HOST/assistant/chat/$ASSISTANT_NAME/context" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "accept: application/json" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "Describe the symbol on the paper tray that indicates the maximum fill level.",
      "multimodal": true,
      "include_binary_content": true
    }'
  ```
</CodeGroup>

<Note>
  If you set `multimodal` to true and `include_binary_content` to false, image objects are not returned in the snippets. If you set `multimodal` to false, only text snippets are returned.
</Note>

Response:

<CodeGroup>
  ```shell Python theme={null}
  # Formatted for readability
  ContextResponse(
    id='00000000000000001e3ef84bd493e612', 
    snippets=[
      MultimodalSnippet(
        type='multimodal', 
        content=[
          TextBlock(type='text', text="..."), 
          ImageBlock(
            type='image', 
            caption='...', 
            image=Image(mime_type='image/jpeg', data='...', type='base64')), 
          // ...
        ], 
        score=0.16321887, 
        reference=PdfReference(
          type='pdf', 
          pages=[3, 4, 5, 6, 7, 8, 9, 10, 11], 
          file=FileModel(
            name='document.pdf', 
            id='9c322597-58d6-4ebc-84b5-a398b620da01', 
            metadata=None, 
            created_on='2025-08-28T23:41:41.982805815Z', 
            updated_on='2025-08-28T23:42:09.562949544Z', 
            status='Available', 
            signed_url='https://storage.googleapis.com/...',
            size=1236044,
            multimodal=True
          )
        )
      ), 
      // ...
    ], 
    usage=TokenCounts(
      prompt_tokens=7061, 
      completion_tokens=0, 
      total_tokens=7061
    )
  )
  ```

  ```json curl theme={null}
  {
    "snippets": [
      {
        "type": "multimodal",
        "content": [
          {
            "type": "text",
            "text": "# The Online User's Guide..."
          },
          {
            "type": "image",
            "caption": "An image of a control panel...",
            "image": {
              "type": "base64",
              "mime_type": "image/jpeg",
              "data": "..."
            }
          },
          // ...
        ],
        "score": 0.16775002,
        "reference": {
          "type": "pdf",
          "file": {
            "status": "Available",
            "id": "a89f678c-9ceb-40ec-8fc7-23913e560b37",
            "name": "document.pdf",
            "size": 1236044,
            "metadata": null,
            "multimodal": true,
            "updated_on": "2025-08-18T23:21:59.697988967Z",
            "created_on": "2025-08-18T23:21:36.498381046Z",
            "signed_url": "https://storage.googleapis.com/..."
          },
          "pages": [ 3, 4, 5, 6, 7, 8, 9, 10, 11 ]
        }
      },
      // ...
    ],
    "usage": {
      "prompt_tokens": 6778,
      "completion_tokens": 0,
      "total_tokens": 6778
    },
    "id": "000000000000000005b9cd91b1c5446d"
  } 
  ```
</CodeGroup>

<Note>
  Snippets are returned based on their semantic relevance to the provided query. When you set `multimodal` to true, you'll receive the most relevant snippets, regardless of the types of content they contain. You can receive text snippets, multimodal snippets, or both.
</Note>

## Limits

Multimodal context for assistants is only available for PDF files. Additionally, the following limits apply:

Multimodal PDF processing uses the same [ingestion unit](/guides/assistant/pricing-and-limits#ingestion) as standard uploads; it is billed at about **twice** the standard per-unit rate (see [Pricing and limits](/guides/assistant/pricing-and-limits)). Object and rate limits for assistants also apply—see [#limits](/guides/assistant/pricing-and-limits#limits) and [#rate-limits](/guides/assistant/pricing-and-limits#rate-limits).

| Metric        | Starter plan | Builder plan | Standard plan | Enterprise plan |
| :------------ | :----------- | :----------- | :------------ | :-------------- |
| Max file size | 10 MB        | 10 MB        | 50 MB         | 50 MB           |
| Page limit    | 100          | 100          | 100           | 100             |

To learn about other assistant-related limits, see [Pinecone Assistant limits](/guides/assistant/pricing-and-limits).


# Pinecone Assistant
Source: https://docs.pinecone.io/guides/assistant/overview

Overview of Pinecone Assistant, a managed service for building production-grade RAG chat and agent applications grounded in your data.

<CardGroup>
  <Card title="Assistant quickstart" icon="comments" href="/guides/assistant/quickstart/sdk-quickstart">
    Create an AI assistant that answers complex questions about your proprietary data
  </Card>

  <Card title="Database quickstart" icon="database" href="/guides/get-started/quickstart">
    Set up a fully managed vector database for high-performance semantic search
  </Card>
</CardGroup>

<Tip>
  Looking for a no-code way to publish a knowledge app with citations, governed access, and versioned releases? See [Pinecone Marketplace](/guides/marketplace/overview) (in [public preview](/release-notes/feature-availability)).
</Tip>

## Use cases

Pinecone Assistant is useful for a variety of tasks, especially for the following:

* Prototyping and deploying an AI assistant quickly.
* Providing context-aware answers about your proprietary data without training an LLM.
* Retrieving answers grounded in your data, with references.

## SDK support

You can use the [Assistant API](/reference/api/latest/assistant/) directly, through the [Pinecone Python SDK](/reference/sdks/python/overview), or through the [Pinecone Node.js SDK](/reference/sdks/node/overview).

## Workflow

You can use the Pinecone Assistant through the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/assistant) or [Pinecone API](/reference/api/latest/assistant/list_assistants).

<Tabs>
  <Tab title="Overview">
    The following steps outline the general Pinecone Assistant workflow:

    <Steps>
      <Step title="Create an assistant">
        [Create an assistant](/guides/assistant/create-assistant) to answer questions about your documents.
      </Step>

      <Step title="Upload documents">
        [Upload documents](/guides/assistant/upload-files) to your assistant. Your assistant manages chunking, embedding, and storage for you.
      </Step>

      <Step title="Chat with an assistant">
        [Chat with your assistant](/guides/assistant/chat-with-assistant) and receive responses as a JSON object or as a text stream. For each chat, your assistant queries a large language model (LLM) with context from your documents to ensure the LLM provides grounded responses.
      </Step>

      <Step title="Evaluate answers">
        [Evaluate the assistant's responses](/guides/assistant/evaluation-overview) for correctness and completeness.
      </Step>

      <Step title="Optimize performance">
        [Use custom instructions](https://www.pinecone.io/learn/assistant-api-deep-dive/#Custom-Instructions) to tailor your assistant's behavior and responses to specific use cases or requirements. [Filter by metadata associated with files](https://www.pinecone.io/learn/assistant-api-deep-dive/#Using-Metadata) to reduce latency and improve the accuracy of responses.
      </Step>

      <Step title="Retrieve context snippets">
        [Retrieve context snippets](/guides/assistant/retrieve-context-snippets) to understand what relevant data snippets Pinecone Assistant is using to generate responses. You can use the retrieved snippets with your own LLM, RAG application, or agentic workflow.
      </Step>
    </Steps>

    <Note>
      For information on how the Pinecone Assistant works, see [Assistant architecture](/reference/architecture/assistant-architecture).
    </Note>
  </Tab>

  <Tab title="Code sample">
    The following code samples outline the Pinecone Assistant workflow using either the [Pinecone Python SDK](/reference/sdks/python/overview) and [Pinecone Assistant plugin](/reference/sdks/python/overview#install-the-pinecone-assistant-python-plugin) or the [Pinecone Node.js SDK](/reference/sdks/node/overview).

    <CodeGroup>
      ```python Python theme={null}
      # pip install pinecone
      # pip install pinecone-plugin-assistant

      from pinecone import Pinecone
      import requests
      from pinecone_plugins.assistant.models.chat import Message

      pc = Pinecone(api_key="YOUR_API_KEY")

      # Create an assistant.
      assistant = pc.assistant.create_assistant(
          assistant_name="example-assistant", 
          instructions="Use American English for spelling and grammar.", # Description or directive for the assistant to apply to all responses.
          region="us", # Region to deploy assistant. Options: "us" (default) or "eu".    
          timeout=30 # Maximum seconds to wait for assistant status to become "Ready" before timing out.
      )

      # Upload a file to your assistant.
      response = assistant.upload_file(
          file_path="/Users/jdoe/Downloads/Netflix-10-K-01262024.pdf",
          metadata={"company": "netflix", "document_type": "form 10k"},
          timeout=None
      )

      # Set up for evaluation later.
      payload = {
          "question": "Who is the CFO of Netflix?", # Question to ask the assistant.
          "ground_truth_answer": "Spencer Neumann" # Expected answer to evaluate the assistant's response.
      }

      # Chat with the assistant.
      msg = Message(role="user", content=payload["question"])
      resp = assistant.chat(messages=[msg], model="gpt-4o")
      print(resp)

      # {
      #    'id': '0000000000000000163008a05b317b7b', 
      #    'model': 'gpt-4o-2024-05-13', 
      #    'usage': {
      #        'prompt_tokens': 9259, 
      #        'completion_tokens': 30, 
      #        'total_tokens': 9289
      #        }, 
      #        'message': {
      #            'content': 'The Chief Financial Officer (CFO) of Netflix is Spencer Neumann.', 
      #            'role': '"assistant"'
      #            }, 
      #            'finish_reason': 'stop', 
      #            'citations': [
      #                {
      #                    'position': 63, 
      #                    'references': [
      #                        {
      #                            'pages': [78, 72, 79], 
      #                            'file': {
      #                                'name': 'Netflix-10-K-01262024.pdf', 
      #                                'id': '76a11dd1...', 
      #                                'metadata': {
      #                                    'company': 'netflix', 
      #                                    'document_type': 'form 10k'
      #                                    }, 
      #                                    'created_on': '2024-12-06T01:29:07.369208590Z', 
      #                                    'updated_on': '2024-12-06T01:29:50.923493799Z', 
      #                                    'status': 'Available', 
      #                                    'signed_url': 'https://storage.googleapis.com/...',
      #                                    'size': 1073470.0
      #                                }
      #                            }
      #                        ]
      #                    }
      #                ]
      #            }

      # Evaluate the assistant's response.
      payload["answer"] = resp.message.content

      headers = {
          "Api-Key": "YOUR_API_KEY",
          "Content-Type": "application/json"
      }

      url = "https://prod-1-data.ke.pinecone.io/assistant/evaluation/metrics/alignment"

      response = requests.request("POST", url, json=payload, headers=headers)

      print(response.text)

      # {
      #    "metrics":
      #    {
      #        "correctness":1.0,
      #        "completeness":1.0,
      #        "alignment":1.0
      #    },
      #    "reasoning":
      #    {
      #        "evaluated_facts":
      #        [
      #            {
      #                "fact":
      #                {
      #                    "content":"Spencer Neumann is the CFO of Netflix."
      #                    },
      #                    "entailment":"entailed"
      #                }
      #            ]
      #        },
      #        "usage":
      #        {
      #            "prompt_tokens":1221,
      #            "completion_tokens":24,
      #            "total_tokens":1245
      #            }
      #        }
      ```

      ```javascript JavaScript theme={null}
      import { Pinecone } from "@pinecone-database/pinecone";

      function sleep(ms) {
        return new Promise((resolve) => setTimeout(resolve, ms));
      }

      async function testPinecone() {
        try {
          console.log("Initializing Pinecone client...");

          const pc = new Pinecone({
            apiKey: "YOUR_API_KEY",
          });

          console.log("Pinecone client initialized successfully.");

          const assistantName = "test-assistant";

          // Create a new assistant.
          console.log(`Creating new assistant: ${assistantName}...`);
          await pc.createAssistant({
            name: assistantName,
            region: "us",
            metadata: { 'test-key': 'test-value' },
          });

          // Validate Assistant was created through describe.
          const asstDesc = await pc.describeAssistant(assistantName);
          console.log(`Described Assistant: ${JSON.stringify(asstDesc)}`);

          // Delay to ensure the Assistant is ready.
          await sleep(4000);

          // Upload file
          const assistant = pc.Assistant(assistantName);
          await assistant.uploadFile({
            path: '/Users/jdoe/Downloads/Netflix-10-K-01262024.pdf',
            metadata: { 'test-key': 'test-value' },
          });
          console.log("File uploaded. Processsing...");

          // Delay to ensure file is available.
          await sleep(45000);

          // Chat
          const chatResp = await assistant.chat({
            messages: [{ role: 'user', content: 'Who is the CFO of Netflix?' }]
          });
          console.log(chatResp);
          
        // Error handling
        } catch (error) {
          console.error("Error:", error);
        }
      }

      // Run the sample code
      testAssistant();
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Learn more

<CardGroup>
  <Card title="API Reference" icon="code-simple" href="/reference">
    Comprehensive details about the Pinecone APIs, SDKs, utilities, and architecture.
  </Card>

  <Card title="Blog" icon="blog" href="https://www.pinecone.io/learn/assistant-api-deep-dive/">
    Four features of the Assistant API you aren't using - but should
  </Card>

  <Card title="Releases" icon="party-horn" href="/release-notes">
    News about features and changes in Pinecone and related tools.
  </Card>
</CardGroup>


# Pricing and limits
Source: https://docs.pinecone.io/guides/assistant/pricing-and-limits

Understand Pinecone Assistant pricing for ingestion units, chat tokens, and storage, plus plan-based service limits for file uploads and knowledge size.

Pricing and limits vary based on [subscription plan](https://www.pinecone.io/pricing/).

## Pricing

Pinecone Assistant usage is billed monthly. Costs can include:

* [Minimum usage](#minimum-usage) (Builder, Standard, and Enterprise plans)
* [Ingestion](#ingestion) (file uploads)
* [Tokens](#tokens) (chat, context retrieval, and evaluation)
* [Storage](#storage)

### Minimum usage

The Builder, Standard, and Enterprise [pricing plans](https://www.pinecone.io/pricing/) include a monthly minimum usage commitment:

| Plan       | Minimum usage     |
| ---------- | ----------------- |
| Starter    | \$0/month         |
| Builder    | \$20/month (flat) |
| Standard   | \$50/month        |
| Enterprise | \$500/month       |

On the Builder plan, the monthly minimum is a flat fee that covers included usage; additional usage beyond [Builder limits](/reference/api/database-limits) is blocked rather than billed. On the Standard and Enterprise plans, customers are charged for what they use each month beyond the monthly minimum.

The minimum is a commitment you grow into rather than an extra charge. Once your usage exceeds the minimum, you pay only for what you use.

**Examples**

<AccordionGroup>
  <Accordion title="Usage below monthly minimum">
    * You are on the Standard plan.
    * Your usage for the month of August amounts to \$20.
    * Your usage is below the \$50 monthly minimum, so your total for the month is \$50.

    In this case, the August invoice would include line items for each service you used (totaling \$20), plus a single line item covering the rest of the minimum usage commitment (\$30).
  </Accordion>

  <Accordion title="Usage exceeds monthly minimum">
    * You are on the Standard plan.
    * Your usage for the month of August amounts to \$100.
    * Your usage exceeds the \$50 monthly minimum, so your total for the month is \$100.

    In this case, the August invoice would only show line items for each service you used (totaling \$100). Since your usage exceeds the minimum usage commitment, you are only charged for your actual usage and no additional minimum usage line item appears on your invoice.
  </Accordion>
</AccordionGroup>

### Ingestion

When you upload or replace files for an assistant, usage is measured in **ingestion units**. One ingestion unit is approximately **400 tokens** (\~300 words); exact counts can vary by document.

| Processing path         | Rate (per ingestion unit) |
| ----------------------- | ------------------------- |
| Standard file ingestion | \$0.0005                  |

*Multimodal PDF processing uses the same ingestion unit; it is billed at about **twice** the standard per-unit rate. For current rates, see [Pricing](https://www.pinecone.io/pricing/).*

| Plan       | File uploads (ingestion units) |
| ---------- | ------------------------------ |
| Starter    | **1,000 / month** included     |
| Builder    | **10,000 / month** included    |
| Standard   | Pay per unit at the rate above |
| Enterprise | Pay per unit at the rate above |

Multimodal ingestion applies to content processed through the [multimodal PDF](/guides/assistant/multimodal) path. Standard ingestion applies to other supported file types.

Usage and invoices reflect a single ingestion usage line item. With [API version](/reference/api/versioning) `2026-04` or later, a completed file-ingestion operation may include **`ingestion_units`**. Use [Describe an operation](/reference/api/2026-04/assistant/describe_operation) or [Track file operations](/guides/assistant/manage-files#track-file-operations) for details.

<a />

### Tokens

For paid plans, you are charged for the number of tokens used by each assistant. [Ingestion](#ingestion) is billed separately from chat and context retrieval tokens.

#### Chat tokens

[Chatting with an assistant](/guides/assistant/chat-with-assistant) involves both input and output tokens:

* **Input tokens** are based on the messages sent to the assistant and the context snippets retrieved from the assistant and sent to a model. Messages sent to the assistant can include messages from the [chat history](/guides/assistant/chat-with-assistant#provide-conversation-history) in addition to the newest message.

* **Output tokens** are based on the answer from the model.

| Plan       | Input token rate                 | Output token rate                |
| ---------- | -------------------------------- | -------------------------------- |
| Starter    | Included (**500,000 / month**\*) | Included (**300,000 / month**)   |
| Builder    | Included (**2,000,000 / month**) | Included (**1,000,000 / month**) |
| Standard   | \$8/million tokens               | \$15/million tokens              |
| Enterprise | \$8/million tokens               | \$15/million tokens              |

*\*1,000,000 input tokens/month to explore [Marketplace apps](/guides/marketplace) until June 30, 2026.*

<Note>
  Chat input tokens appear as "Assistants Input Tokens" on invoices and `prompt_tokens` in API responses. Chat output tokens appear as "Assistants Output Tokens" on invoices and `completion_tokens` in API responses.
</Note>

#### Context tokens

When you [retrieve context snippets](/guides/assistant/context-snippets-overview), tokens are based on the messages sent to the assistant and the context snippets retrieved from the assistant. Messages sent to the assistant can include messages from the [chat history](/guides/assistant/chat-with-assistant#provide-conversation-history) in addition to the newest message.

| Plan       | Token rate                       |
| ---------- | -------------------------------- |
| Starter    | Included (**500,000 / month**)   |
| Builder    | Included (**2,000,000 / month**) |
| Standard   | \$5/million tokens               |
| Enterprise | \$5/million tokens               |

<Note>
  Context retrieval tokens appear as **Assistants Context Tokens Processed** on invoices and `prompt_tokens` in API responses. In API responses, `completion_tokens` will always be 0 because, unlike for chat, there is no answer from a model.
</Note>

#### Evaluation tokens

[Evaluating responses](/guides/assistant/evaluation-overview) involves both input and output tokens:

* **Input tokens** are based on two requests to a model: The first request contains a question, answer, and ground truth answer, and the second request contains the same details plus generated facts returned by the model for the first request.
* **Output tokens** are based on two responses from a model: The first response contains generated facts, and the second response contains evaluation metrics.

| Plan       | Input token rate   | Output token rate   |
| ---------- | ------------------ | ------------------- |
| Starter    | Not available      | Not available       |
| Builder    | Not available      | Not available       |
| Standard   | \$8/million tokens | \$15/million tokens |
| Enterprise | \$8/million tokens | \$15/million tokens |

<Note>
  Evaluation input tokens appear as **Assistants Evaluation Tokens Processed** on invoices and `prompt_tokens` in API responses. Evaluation output tokens appear as **Assistants Evaluation Tokens Out** on invoices and `completion_tokens` in API responses.
</Note>

### Storage

For paid plans, you are charged for the size of each assistant.

| Plan       | Storage rate            |
| ---------- | ----------------------- |
| Starter    | Free (1 GB max per org) |
| Builder    | Free up to 3 GB per org |
| Standard   | \$3/GB per month        |
| Enterprise | \$3/GB per month        |

## Limits

Pinecone Assistant limits vary based on [subscription plan](https://www.pinecone.io/pricing/).

### Object limits

Object limits are restrictions on the number or size of assistant-related objects. Limits below are scoped **per organization** except for **Assistants per project**, which is scoped per project.

| Metric                              | Starter plan      | Builder plan      | Standard plan | Enterprise plan |
| :---------------------------------- | :---------------- | :---------------- | :------------ | :-------------- |
| Assistants per project              | 5                 | 200               | Unlimited     | Unlimited       |
| File storage per org                | 1 GB              | 3 GB              | Unlimited     | Unlimited       |
| Chat input tokens per org           | 500,000 / month\* | 2,000,000 / month | Unlimited     | Unlimited       |
| Chat output tokens per org          | 300,000 / month   | 1,000,000 / month | Unlimited     | Unlimited       |
| Context retrieval tokens per org    | 500,000 / month   | 2,000,000 / month | Unlimited     | Unlimited       |
| Ingestion units per org             | 1,000 / month     | 10,000 / month    | Unlimited     | Unlimited       |
| File size (.docx, .json, .md, .txt) | 10 MB             | 10 MB             | 10 MB         | 10 MB           |
| File size (.pdf)                    | 10 MB             | 50 MB             | 100 MB        | 100 MB          |
| Metadata size per file              | 16 KB             | 16 KB             | 16 KB         | 16 KB           |

*\*1,000,000 input tokens/month to explore [Marketplace apps](/guides/marketplace) until June 30, 2026.*

Additionally, the following limits apply to [multimodal PDFs](/guides/assistant/multimodal) (currently in [public preview](/release-notes/feature-availability)):

Multimodal PDF processing uses the same [ingestion unit](/guides/assistant/pricing-and-limits#ingestion) as standard uploads; it is billed at about **twice** the standard per-unit rate (see [Pricing and limits](/guides/assistant/pricing-and-limits)). Object and rate limits for assistants also apply—see [#limits](/guides/assistant/pricing-and-limits#limits) and [#rate-limits](/guides/assistant/pricing-and-limits#rate-limits).

| Metric        | Starter plan | Builder plan | Standard plan | Enterprise plan |
| :------------ | :----------- | :----------- | :------------ | :-------------- |
| Max file size | 10 MB        | 10 MB        | 50 MB         | 50 MB           |
| Page limit    | 100          | 100          | 100           | 100             |

### Rate limits

Rate limits help protect your applications from misuse and maintain the health of our shared infrastructure. These limits are designed to support typical production workloads while ensuring reliable performance for all users.

**Most rate limits can be adjusted upon request.** If you need higher limits to scale your application, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) with details about your use case.

Requests that exceed a rate limit fail and return a `429 - TOO_MANY_REQUESTS` status.

<Tip>To handle rate limits, implement [retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic).</Tip>

| Metric                                      | Starter plan  | Builder plan  | Standard plan | Enterprise plan |
| :------------------------------------------ | :------------ | :------------ | :------------ | :-------------- |
| Assistant list/get requests per minute      | 40            | 50            | 100           | 500             |
| Assistant create/update requests per minute | 20            | 25            | 50            | 100             |
| Assistant delete requests per minute        | 20            | 25            | 50            | 100             |
| File get requests per minute                | 100           | 150           | 300           | 6,000           |
| File list requests per minute               | 50            | 75            | 150           | 3,000           |
| File upload requests per minute             | 5             | 15            | 20            | 300             |
| Multimodal PDF upload requests per minute   | 5             | 10            | 20            | 40              |
| File delete requests per minute             | 5             | 15            | 20            | 300             |
| Chat input tokens per minute                | 100,000       | 200,000       | 300,000       | 1,000,000       |
| Chat history tokens per query               | 64,000        | 64,000        | 64,000        | 64,000          |
| Evaluation input tokens per minute          | Not available | Not available | 150,000       | 500,000         |


# Pinecone Assistant: n8n quickstart
Source: https://docs.pinecone.io/guides/assistant/quickstart/n8n-quickstart

Build an n8n workflow with Pinecone Assistant and OpenAI to download files via HTTP, upload documents, and chat with them from an automation.

Create an [n8n](https://docs.n8n.io/choose-n8n/) workflow that that downloads files via HTTP, uploads them to Pinecone Assistant, and enables you to chat with documents using OpenAI.

## 1. Create an assistant

[Create an assistant](https://app.pinecone.io/organizations/-/projects/-/assistant) in the Pinecone console:

* Name your assistant `n8n-assistant`.

## 2. Install the Pinecone Assistant node

In your n8n account, install the Pinecone Assistant node using the nodes panel:

<img />

<img />

<Note>
  Restart your n8n workspace if the Pinecone Assistant node doesn't appear in the nodes panel.
</Note>

## 3. Create a new workflow

Copy this workflow template URL:

```shell theme={null}
https://raw.githubusercontent.com/pinecone-io/n8n-templates/refs/heads/main/assistant-quickstart/assistant-quickstart.json
```

In your n8n account, [create a new workflow](https://docs.n8n.io/workflows/create/) and paste the URL anywhere in the workflow editor. Click **Import** to add the workflow.

## 4. Add credentials

<Steps>
  <Step title="Authenticate with Pinecone">
    * Use the **Connect to Pinecone** button in the node to connect to a new or existing Pinecone account:

    <img />

    <img />

    * If you self-host n8n, add your [Pinecone API key](https://app.pinecone.io/organizations/-/keys) directly.
  </Step>

  <Step title="Add your OpenAI credentials">
    * In the **OpenAI Chat Model** node, select **Credential to connect with > Create new credential** and paste in your OpenAI API key.
  </Step>
</Steps>

## 5. Execute the workflow

By default, the workflow downloads recent Pinecone release notes and uploads them to your assistant. Click **Execute workflow** to start uploading documents.

<Tip>
  You can add your own files to the workflow by changing the URLs in the **Set file urls** node.
</Tip>

## 4. Chat with your docs

Once the documents are uploaded, you can chat with your assistant. In the n8n workflow, use the **Chat input** node to ask questions like:

```
What support does Pinecone have for MCP?
```

## Next steps

* Customize the workflow for your own use case:
  * Change the urls in the **Set file urls** node to use your own files.
  * Customize the system message on the **AI Agent** node to indicate what kind of knowledge is stored in Pinecone Assistant.
  * To help manage token consumption, add the Top K and/or Snippet Size parameters to the **Get context from Assistant** node.
  * Filter the context snippets even further by adding metadata filters to the **Get context from Assistant** node.
* Use n8n, Pinecone Assistant, and OpenAI to [chat with your Google Drive documents](https://n8n.io/workflows/9942-rag-powered-document-chat-with-google-drive-openai-and-pinecone-assistant/).
* Learn more about [Pinecone Assistant](/guides/assistant/overview).
* Get help in the [Pinecone Discord community](https://discord.gg/tJ8V62S3sH).


# Pinecone Assistant: SDK quickstart
Source: https://docs.pinecone.io/guides/assistant/quickstart/sdk-quickstart

Quickstart for Pinecone Assistant using the Python or Node.js SDK to create an assistant, upload documents, and chat with your data via RAG.

Use a Pinecone SDK to create an assistant, upload documents, and chat with the assistant.

<Tip>
  To get started in your browser, use the [Assistant Quickstart colab notebook](https://colab.research.google.com/github/pinecone-io/examples/blob/master/docs/assistant-quickstart.ipynb).
</Tip>

## 1. Install an SDK

The Pinecone [Python SDK](/reference/sdks/python/overview) and [Node.js SDK](/reference/sdks/node/overview) provide convenient programmatic access to the [Assistant API](/reference/api/latest/assistant/).

<CodeGroup>
  ```shell Python theme={null}
  pip install pinecone
  pip install pinecone-plugin-assistant
  ```

  ```shell JavaScript theme={null}
  npm install @pinecone-database/pinecone
  ```
</CodeGroup>

## 2. Get an API key

You need an API key to make calls to your assistant.

Create a new API key in the [Pinecone console](https://app.pinecone.io/organizations/-/keys), or use the widget below to generate a key. If you don't have a Pinecone account, the widget will sign you up for the free [Starter plan](https://www.pinecone.io/pricing/).

<div>
  <div>
    <div>
      <div />
    </div>
  </div>
</div>

Your generated API key:

```shell theme={null}
"{{YOUR_API_KEY}}"
```

## 3. Create an assistant

[Create an assistant](/reference/api/latest/assistant/create_assistant), as in the following example:

<CodeGroup>
  ```python Python theme={null}
  from pinecone import Pinecone

  pc = Pinecone(api_key="{{YOUR_API_KEY}}")

  assistant = pc.assistant.create_assistant(
      assistant_name="example-assistant", 
      instructions="Use American English for spelling and grammar.", # Description or directive for the assistant to apply to all responses.
      region="us", # Region to deploy assistant. Options: "us" (default) or "eu".
      timeout=30 # Maximum seconds to wait for assistant status to become "Ready" before timing out.
  )
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone'

  const pc = new Pinecone({ apiKey: "{{YOUR_API_KEY}}" });

  const assistant = await pc.createAssistant({
    name: 'example-assistant',
    instructions: 'Use American English for spelling and grammar.', // Description or directive for the assistant to apply to all responses.
    region: 'us'
  });
  ```
</CodeGroup>

## 4. Upload a file to the assistant

With Pinecone Assistant, you can upload documents, ask questions, and receive responses that reference your documents. This is known as retrieval-augmented generation (RAG).

For this quickstart, [download a sample 10-k filing file](https://s22.q4cdn.com/959853165/files/doc_financials/2023/ar/Netflix-10-K-01262024.pdf) to your local device.

Next, [upload the file](/reference/api/latest/assistant/upload_file) to your assistant:

<CodeGroup>
  ```python Python theme={null}
  # Get the assistant.
  assistant = pc.assistant.Assistant(
      assistant_name="example-assistant", 
  )

  # Upload a file.
  response = assistant.upload_file(
      file_path="/path/to/file/Netflix-10-K-01262024.pdf",
      metadata={"company": "netflix", "document_type": "form 10k"},
      timeout=None
  )
  ```

  ```javascript JavaScript theme={null}
  const assistantName = 'example-assistant';
  const assistant = pc.Assistant(assistantName);

  await assistant.uploadFile({
    path: '/Users/jdoe/Downloads/example_file.txt'
  });
  ```
</CodeGroup>

## 5. Chat with the assistant

With the sample file uploaded, you can now [chat with the assistant](/reference/api/latest/assistant/chat_assistant). Ask the assistant questions about your document. It returns either a JSON object or a text stream.

<Tip>
  For faster chat responses, use GPT models (`gpt-4o`, `gpt-4.1`, `gpt-5`, or `o4-mini`). You can also enable streaming to improve perceived latency by showing content as it's generated.
</Tip>

The following example requests a default response to the message, "Who is the CFO of Netflix?":

<CodeGroup>
  ```python Python theme={null}
  from pinecone_plugins.assistant.models.chat import Message

  msg = Message(role="user", content="Who is the CFO of Netflix?")
  resp = assistant.chat(messages=[msg])

  print(resp)
  ```

  ```javascript JavaScript theme={null}
  const chatResp = await assistant.chat({
    messages: [{ role: 'user', content: 'Who is the CFO of Netflix?' }],
    model: 'gpt-4o'
  });

  console.log(chatResp);
  ```
</CodeGroup>

The example above returns a response like the following:

```
{
    'id': '0000000000000000163008a05b317b7b', 
    'model': 'gpt-4o-2024-05-13', 
    'usage': {
        'prompt_tokens': 9259, 
        'completion_tokens': 30, 
        'total_tokens': 9289
        }, 
        'message': {
            'content': 'The Chief Financial Officer (CFO) of Netflix is Spencer Neumann.', 
            'role': '"assistant"'
            }, 
            'finish_reason': 'stop', 
            'citations': [
                {
                    'position': 63, 
                    'references': [
                        {
                            'pages': [78, 72, 79], 
                            'file': {
                                'name': 'Netflix-10-K-01262024.pdf', 
                                'id': '76a11dd1...', 
                                'metadata': {
                                    'company': 'netflix', 
                                    'document_type': 'form 10k'
                                    }, 
                                    'created_on': '2024-12-06T01:29:07.369208590Z', 
                                    'updated_on': '2024-12-06T01:29:50.923493799Z', 
                                    'status': 'Available', 
                                    'signed_url': 'https://storage.googleapis.com/...',
                                    'size': 1073470.0
                                }
                            }
                        ]
                    }
                ]
            }
```

<Warning>
  [`signed_url`](https://cloud.google.com/storage/docs/access-control/signed-urls) provides temporary, read-only access to the relevant file. Anyone with the link can access the file, so treat it as sensitive data. Expires in one hour.
</Warning>

## 6. Clean up

When you no longer need the `example-assistant`, [delete the assistant](/reference/api/latest/assistant/delete_assistant):

<Warning>
  Deleting an assistant also deletes all files uploaded to the assistant.
</Warning>

<CodeGroup>
  ```python Python theme={null}
  pc.assistant.delete_assistant(
      assistant_name="example-assistant", 
  )
  ```

  ```javascript JavaScript theme={null}
  await pc.deleteAssistant('example-assistant');
  ```
</CodeGroup>

## Next steps

* Learn more about [Pinecone Assistant](/guides/assistant/overview)
* Learn about [additional assistant features](https://www.pinecone.io/learn/assistant-api-deep-dive/)
* [Evaluate](/guides/assistant/evaluate-answers) the assistant's responses
* View a [sample app](/examples/sample-apps/pinecone-assistant) that uses Pinecone Assistant


# Retrieve context snippets
Source: https://docs.pinecone.io/guides/assistant/retrieve-context-snippets

Retrieve context snippets and citations from a Pinecone Assistant to power your own LLM, RAG application, or agentic workflow with signed URLs.

This page shows you how to [retrieve context snippets](/guides/assistant/context-snippets-overview).

<Tip>
  To try this in your browser, use the [Pinecone Assistant - Context colab notebook](https://colab.research.google.com/drive/1AD4QWsXBG1FQRwq-ModlaggR7Cx7NJCz).
</Tip>

## Retrieve context snippets from an assistant

You can [retrieve context snippets](/reference/api/latest/assistant/context_assistant) from an assistant, as in the following example:

<CodeGroup>
  ```python Python theme={null}
  # To use the Python SDK, install the plugin:
  # pip install --upgrade pinecone pinecone-plugin-assistant

  from pinecone import Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")
  assistant = pc.assistant.Assistant(assistant_name="example-assistant")

  response = assistant.context(query="Who is the CFO of Netflix?")

  for snippet in response.snippets:
      print(snippet)
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone'

  const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' });

  const assistantName = 'example-assistant';
  const assistant = pc.Assistant(assistantName);
  const response = await assistant.context({
    query: 'Who is the CFO of Netflix?',
  });
  console.log(response);
  ```

  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  ASSISTANT_NAME="example-assistant"

  curl "https://prod-1-data.ke.pinecone.io/assistant/chat/$ASSISTANT_NAME/context" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "accept: application/json" \
    -H "Content-Type: application/json" \
    -H "X-Pinecone-Api-Version: 2025-10" \
    -d '{
      "query": "Who is the CFO of Netflix?"
  }'
  ```
</CodeGroup>

The example above returns a JSON object like the following:

```json JSON theme={null}
{
    "snippets":
    [
        {
            "type":"text",
            "content":"EXHIBIT 31.3\nCERTIFICATION OF CHIEF FINANCIAL OFFICER\nPURSUANT TO SECTION 302 OF THE SARBANES-OXLEY ACT OF 2002\nI, Spencer Neumann, certify that: ..."
            "score":0.9960699,
            "reference":
            {
                "type":"pdf",
                "file":
                {
                    "status":"Available",
                    "id":"e6034e51-0bb9-4926-84c6-70597dbd07a7",
                    "name":"Netflix-10-K-01262024.pdf",
                    "size":1073470,
                    "metadata":null,
                    "updated_on":"2024-11-21T22:59:10.426001030Z",
                    "created_on":"2024-11-21T22:58:35.879120257Z", 
                    "signed_url":"https://storage.googleapis.com..."
                    },
                "pages":[78]
            }
        },
{
    "type":"text",
    "content":"EXHIBIT 32.1\n..."
...
```

<Warning>
  [`signed_url`](https://cloud.google.com/storage/docs/access-control/signed-urls) provides temporary, read-only access to the relevant file. Anyone with the link can access the file, so treat it as sensitive data. Expires in one hour.
</Warning>

## Control the snippets retrieved

<Note>
  This is available in API versions `2025-04` and later.
</Note>

You can limit [token usage](/guides/assistant/pricing-and-limits#token-usage) by tuning `top_k * snippet_size`:

* `snippet_size`: Controls the max size of a snippet (default is 2048 tokens). Note that snippet size can vary and, in rare cases, may be bigger than the set `snippet_size`. Snippet size controls the amount of context given for each chunk of text.
* `top_k`: Controls the max number of context snippets retrieved (default is 16). `top_k` controls the diversity of information received in the returned snippets.

While additional tokens will be used for other parameters, adjusting the `top_k` and `snippet_size` can help manage token consumption.

<CodeGroup>
  ```python Python theme={null}
  # To use the Python SDK, install the plugin:
  # pip install --upgrade pinecone pinecone-plugin-assistant

  from pinecone import Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")
  assistant = pc.assistant.Assistant(assistant_name="example-assistant")

  response = assistant.context(query="Who is the CFO of Netflix?", top_k=10, snippet_size=2500)

  for snippet in response.snippets:
      print(snippet)
  ```

  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  ASSISTANT_NAME="example-assistant"

  curl "https://prod-1-data.ke.pinecone.io/assistant/chat/$ASSISTANT_NAME/context" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "accept: application/json" \
    -H "Content-Type: application/json" \
    -H "X-Pinecone-Api-Version: 2025-10" \
    -d '{
      "query": "Who is the CFO of Netflix?",
      "top_k": 10,
      "snippet_size": 2500
  }'
  ```
</CodeGroup>


# Upload files
Source: https://docs.pinecone.io/guides/assistant/upload-files

Upload local files to a Pinecone assistant with Python, JavaScript, or curl, track ingestion operations, and see how uploads are billed as ingestion units.

<Note>
  File upload limitations depend on the plan you are using. For more information, see [Pricing and limitations](/guides/assistant/pricing-and-limits#limits).
</Note>

## Upload a local file

You can [upload a file to your assistant](/reference/api/latest/assistant/upload_file) from your local device, as in the following example.

<CodeGroup>
  ```python Python theme={null}
  # To use the Python SDK, install the plugin:
  # pip install --upgrade pinecone pinecone-plugin-assistant

  from pinecone import Pinecone
  pc = Pinecone(api_key="YOUR_API_KEY")

  # Get an assistant.
  assistant = pc.assistant.Assistant(
      assistant_name="example-assistant", 
  )

  # Upload a file.
  response = assistant.upload_file(
      file_path="/Users/jdoe/Downloads/example_file.txt",
      timeout=None
  )
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone'

  const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' });

  const assistantName = 'example-assistant';
  const assistant = pc.Assistant(assistantName);
  await assistant.uploadFile({
    path: '/Users/jdoe/Downloads/example_file.txt'
  });
  ```

  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  ASSISTANT_NAME="example-assistant"
  LOCAL_FILE_PATH="/Users/jdoe/Downloads/example_file.txt"

  curl -X POST "https://prod-1-data.ke.pinecone.io/assistant/files/$ASSISTANT_NAME" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2026-04" \
    -F "file=@$LOCAL_FILE_PATH"
  ```
</CodeGroup>

File uploads are billed in [ingestion units](/guides/assistant/pricing-and-limits#ingestion). With [API version](/reference/api/versioning) `2026-04` or later, upload, upsert, and delete responses return an operation object. Poll [Describe an operation](/reference/api/2026-04/assistant/describe_operation) or [List operations](/reference/api/2026-04/assistant/list_operations) to track progress; when a file-ingestion operation completes, `ingestion_units` may be present on the operation. See [Track file operations](/guides/assistant/manage-files#track-file-operations).

Upload is asynchronous and returns an operation ID. It may take several minutes for your assistant to process your file. You can [track file operations](/guides/assistant/manage-files#track-file-operations) to monitor progress, or [check the status of your file](/guides/assistant/manage-files#get-the-status-of-a-file) to determine if it is ready to use.

<Tip>
  You can upload a file to an assistant using the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/assistant). Select the assistant you want to upload to and add the file in the Assistant playground.
</Tip>

## Upload a file with metadata

You can upload a file with metadata. Metadata is a dictionary of key-value pairs that you can use to store additional information about the file. For example, you can use metadata to store the file's name, document type, publish date, or any other relevant information.

<CodeGroup>
  ```Python Python theme={null}
  # To use the Python SDK, install the plugin:
  # pip install --upgrade pinecone pinecone-plugin-assistant

  from pinecone import Pinecone
  pc = Pinecone(api_key="YOUR_API_KEY")

  # Get the assistant.
  assistant = pc.assistant.Assistant(
      assistant_name="example-assistant", 
  )

  # Upload a file.
  response = assistant.upload_file(
      file_path="/Users/jdoe/Downloads/example_file.txt",
      metadata={"published": "2024-01-01", "document_type": "manuscript"},
      timeout=None
  )
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone'

  const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' });

  const assistantName = 'example-assistant';
  const assistant = pc.Assistant(assistantName);
  await assistant.uploadFile({
    path: '/Users/jdoe/Downloads/example_file.txt',
    metadata: { 'published': '2024-01-01', 'document_type': 'manuscript' },
  });
  ```

  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  ASSISTANT_NAME="example-assistant"
  LOCAL_FILE_PATH="/Users/jdoe/Downloads/example_file.txt"

  curl -X POST "https://prod-1-data.ke.pinecone.io/assistant/files/$ASSISTANT_NAME" \
      -H "Api-Key: $PINECONE_API_KEY" \
      -H "X-Pinecone-Api-Version: 2026-04" \
      -F "file=@$LOCAL_FILE_PATH" \
      -F 'metadata={"published": "2024-01-01", "document_type": "manuscript"}'
  ```
</CodeGroup>

When a file is uploaded with metadata, you can use the metadata to [filter a list of files](/guides/assistant/manage-files#view-a-filtered-list-of-files) and [filter chat responses](/guides/assistant/chat-with-assistant#filter-chat-with-metadata).

## Upsert a file

<Note>
  This feature requires [API version](/reference/api/versioning) `2026-04` or later.
</Note>

You can create or replace a file by providing a custom file ID using the [upsert file](/reference/api/2026-04/assistant/upsert_file) endpoint. If a file with the given ID already exists, it is replaced. If not, a new file is created.

File IDs must be 1-128 characters long and can contain alphanumeric characters, hyphens, and underscores.

<CodeGroup>
  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  ASSISTANT_NAME="example-assistant"
  FILE_ID="my-custom-file-id"
  LOCAL_FILE_PATH="/Users/jdoe/Downloads/example_file.txt"

  curl -X PUT "https://prod-1-data.ke.pinecone.io/assistant/files/$ASSISTANT_NAME/$FILE_ID" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2026-04" \
    -F "file=@$LOCAL_FILE_PATH"
  ```
</CodeGroup>

Upsert is asynchronous and returns an operation ID. You can [track file operations](/guides/assistant/manage-files#track-file-operations) to monitor progress.

## Upsert a file with metadata

You can upsert a file with metadata by including it as a field in the multipart form:

<CodeGroup>
  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  ASSISTANT_NAME="example-assistant"
  FILE_ID="my-custom-file-id"
  LOCAL_FILE_PATH="/Users/jdoe/Downloads/example_file.txt"

  curl -X PUT "https://prod-1-data.ke.pinecone.io/assistant/files/$ASSISTANT_NAME/$FILE_ID" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2026-04" \
    -F "file=@$LOCAL_FILE_PATH" \
    -F 'metadata={"published": "2024-01-01", "document_type": "manuscript"}'
  ```
</CodeGroup>

## Upload a PDF with multimodal context

Assistants can gather context from images contained in PDF files. To learn more about this feature, see [Multimodal context for assistants](/guides/assistant/multimodal).

## Upload from a binary stream

You can upload a file directly from an in-memory binary stream using the Python SDK and the [BytesIO class](https://docs.python.org/3/library/io.html#io.BytesIO).

<Note>
  When uploading text-based files (like .txt, .md, .json, etc.) through BytesIO streams, make sure the content is encoded in UTF-8 format.
</Note>

```python Python theme={null}
from pinecone import Pinecone
from io import BytesIO

pc = Pinecone(api_key="YOUR_API_KEY")

# Get an assistant
assistant = pc.assistant.Assistant(
    assistant_name="example-assistant", 
)

# Create a BytesIO stream with some content
md_text = "# Title\n\ntext"
# Note: Assistant currently supports only utf-8 for text-based files
stream = BytesIO(md_text.encode("utf-8"))

# Upload the stream
response = assistant.upload_bytes_stream(
    stream=stream,
    file_name="example_file.md",
    timeout=None
)
```


# AI Engine
Source: https://docs.pinecone.io/integrations/ai-engine

Use the AI Engine WordPress plugin with Pinecone to power chatbots, semantic search, and RAG over site content directly from your WordPress dashboard.

AI Engine seamlessly connects WordPress with the world's leading AI models. Create intelligent chatbots, generate content, build AI forms, and automate tasks—all from your WordPress dashboard.

With AI Engine, you can create a chatbot to assist your visitors, answer support questions, or guide users through your products and services. Need fresh content? AI Engine can write posts in your voice, help rewrite existing ones, or translate them naturally into other languages. It can also generate custom images for your articles, refine messy text, or just lend a hand when you're stuck.

For developers and power users, AI Engine offers internal APIs, shortcode flexibility, and advanced features like function calling and real-time audio chat. You can build your own AI-powered tools, automate tasks, or even create AI-driven SaaS applications on top of WordPress. And with support for a wide range of providers — OpenAI, Anthropic, Google, Hugging Face, and more — you have full control over the models you want to use.

Everything is designed to feel native to WordPress. Whether you're exploring ideas in the AI Playground, using Copilot to help in the editor, or letting an AI agent manage your content through MCP, AI Engine is built to grow with you — and shaped by real user feedback every step of the way.

<PrimarySecondaryCTA />


# Amazon Bedrock
Source: https://docs.pinecone.io/integrations/amazon-bedrock

Select Pinecone as a Knowledge Base for Amazon Bedrock to ground LLMs with your enterprise data and build accurate, low-latency RAG applications on AWS.

Users can now select Pinecone as a Knowledge Base for [Amazon Bedrock](https://aws.amazon.com/bedrock/), a fully managed service from Amazon Web Services (AWS) for building GenAI applications.

The Pinecone vector database is a key component of the AI tech stack, helping companies solve one of the biggest challenges in deploying GenAI solutions — hallucinations — by allowing them to store, search, and find the most relevant and up-to-date information from company data and send that context to Large Language Models (LLMs) with every query. This workflow is called Retrieval Augmented Generation (RAG), and with Pinecone, it aids in providing relevant, accurate, and fast responses from search or GenAI applications to end users.

With the release of Knowledge Bases for Amazon Bedrock, developers can integrate their enterprise data into Amazon Bedrock using Pinecone as the fully-managed vector database to build GenAI applications that are:

* **Highly performant:** Speed through data in milliseconds. Leverage metadata filters and support for sparse-dense vectors in a single index for top-notch relevance, ensuring quick, accurate, and grounded results across diverse search tasks.
* **Cost effective at scale:** Start for free on the starter plan and seamlessly scale usage with transparent usage-based pricing. Add or remove resources to meet your desired capacity and performance, upwards of billions of embeddings.
* **Enterprise ready:** Launch, use, and scale your AI solution without needing to maintain infrastructure, monitor services, or troubleshoot algorithms. Pinecone meets the security and operational requirements of enterprises.

<PrimarySecondaryCTA />

## What are Agents for Amazon Bedrock?

In Bedrock, users interact with **Agents** that are capable of combining the natural language interface of the supported LLMs with those of a **Knowledge Base.** Bedrock's Knowledge Base feature uses the supported LLMs to generate **embeddings** from the original data source. These embeddings are stored in Pinecone, and the Pinecone index is used to retrieve semantically relevant content upon the user's query to the agent.

**Note:** the LLM used for embeddings may be different than the one used for the natural language generation. For example, you may choose to use Amazon Titan to generate embeddings and use Anthropic's Claude to generate natural language responses.

Additionally, Agents for Amazon Bedrock may be configured to execute various actions in the context of responding to a user's query - but we won't get into this functionality in this post.

## What is a Knowledge Base for Amazon Bedrock?

A Bedrock Knowledge base ingests raw text data or documents found in Amazon S3, embeds the content and upserts the embeddings into Pinecone. Then, a Bedrock agent can interact with the knowledge base to retrieve the most semantically relevant content given a user's query.

Overall, the Knowledge Base feature is a valuable tool for users who want to improve their AI models' performance. With Bedrock's LLMs and Pinecone, users can easily integrate their data from AWS storage solutions and enhance the accuracy and relevance of their AI models.

In this post, we'll go through the steps required for creating a Knowledge Base for Amazon Bedrock as well as an agent that will retrieve information from the knowledge base.

<img alt="" />

## Setup guide

The process of using a Bedrock knowledge base with Pinecone works as follows:

<Steps>
  <Step title="Create a Pinecone index.">
    Create an empty Pinecone index with an embedding model in mind. The index must be empty for Bedrock integration.
  </Step>

  <Step title="Set up a data source.">
    Upload sample data to Amazon S3.
  </Step>

  <Step title="Create a Bedrock knowledge base.">
    Sync data with Bedrock to create embeddings saved in Pinecone.
  </Step>

  <Step title="Connect Pinecone to Bedrock.">
    Use the knowledge base to reference the data saved in Pinecone.
  </Step>

  <Step title="Create and link agents to Bedrock.">
    Agents can interact directly with the Bedrock knowledge base, which will retrieve the semantically relevant content.
  </Step>
</Steps>

### 1. Create a Pinecone index

The knowledge base stores data in a Pinecone index. Decide which [supported embedding model](https://docs.aws.amazon.com/bedrock/latest/userguide/models-supported.html) to use with Bedrock before you create the index, as your index's dimensions will need to match the model's. For example, the AWS Titan Text Embeddings V2 model can use dimension sizes 1024, 384, and 256.

After signing up to Pinecone, follow the [quickstart guide](/guides/get-started/quickstart) to create your Pinecone index and retrieve your `apiKey` and index host from the [Pinecone console](https://app.pinecone.io).

<Note>
  Your index must have the same dimensions as the model you will later select for creating your embeddings. Also, your index must be empty. All data must be ingested through Bedrock's sync process.
</Note>

### 2. Set up your data source

#### Set up secrets

After setting up your Pinecone index, you'll have to create a secret in [AWS Secrets Manager](https://console.aws.amazon.com/secretsmanager/newsecret):

1. In the **Secret type** section, select **Other type of secret**.
2. In the **Key/value pairs** section, enter a key value pair for the Pinecone API key name and its respective value. For example, use `apiKey` and the API key value.
   <img alt="" />
3. Click **Next**.
4. Enter a **Secret name** and **Description**.
5. Click **Next** to save your key.
6. On the **Configure rotation** page, select all the default options in the next screen, and click **Next**.
7. Click **Store**.
8. Click on the new secret you created and save the secret ARN for a later step.

#### Set up S3

The knowledge base is going to draw on data saved in S3. For this example, we use a [sample of research papers](https://huggingface.co/datasets/jamescalam/ai-arxiv2-semantic-chunks) obtained from a dataset. This data will be embedded and then saved in Pinecone.

1. Create a new general purpose bucket in [Amazon S3](https://console.aws.amazon.com/s3/home).

2. Once the bucket is created, upload a CSV file.

   <Note>
     The CSV file must have a field for text that will be embedded, and a field for metadata to upload with each embedded text.
   </Note>

3. Save your bucket's address (`s3://…`) for the following configuration steps.

### 3. Create a Bedrock knowledge base

To [create a Bedrock knowledge base](https://console.aws.amazon.com/bedrock/home?#/knowledge-bases/create-knowledge-base), use the following steps:

1. Enter a **Knowledge Base name**.
2. In the **Choose data source** section, select **Amazon S3**.
3. Click **Next**.
4. On the **Configure data source** page, enter the **S3 URI** for the bucket you created.
5. If you do not want to use the default chunking strategy, select a chunking strategy.
6. Click **Next**.

### 4. Connect Pinecone to the knowledge base

Now you will need to select an embedding model to configure with Bedrock and configure the data sources.

1. Select the embedding model you decided on earlier.
2. For the **Vector database**, select **Choose a vector store you have created** and select **Pinecone**.
3. Mark the check box for authorizing AWS to access your Pinecone index.

   <Note>
     Ensure your Pinecone index is empty before proceeding. Bedrock cannot work with indexes that contain existing data. All data must be ingested through Bedrock's sync process.
   </Note>
4. For the **Endpoint URL**, enter the Pinecone index host retrieved from the Pinecone console.
5. For the **Credentials secret ARN**, enter the secret ARN you created earlier.
6. In the **Metadata field mapping** section, enter the **Text field name** you want to embed and the **Bedrock-managed metadata field name** that will be used for metadata managed by Bedrock (e.g., `metadata`).
7. Click **Next**.
8. Review your selections and complete the creation of the knowledge base.
9. On the [Knowledge Bases](https://console.aws.amazon.com/bedrock/home?#/knowledge-bases) page select the knowledge base you just created to view its details.
10. Click **Sync** for the newly created data source.
    <Note>
      Sync the data source whenever you add new data to the data source to start the ingestion workflow of converting your Amazon S3 data into vector embeddings and upserting the embeddings into the vector database. Depending on the amount of data, this whole workflow can take some time.
    </Note>

### 5. Create and link an agent to Bedrock

Lastly, [create an agent](https://console.aws.amazon.com/bedrock/home?#/agents) that will use the knowledge base for retrieval:

1. Click **Create Agent**.
2. Enter an **Name** and **Description**.
3. Click **Create**.
4. Select the LLM provider and model you'd like to use.
5. Provide instructions for the agent. These will define what the agent is trying to accomplish.
6. In the **Knowledge Bases** section, select the knowledge base you created.
7. Prepare the agent by clicking **Prepare** near the top of the builder page.
8. Test the agent after preparing it to verify it is using the knowledge base.
9. Click **Save and exit**.

Your agent is now set up and ready to go! In the next section, we'll show how to interact with the newly created agent.

#### Create an alias for your agent

In order to deploy the agent, create an alias for it that points to a specific version of the agent. Once the alias is created, it will display in the agent view.

1. On the [Agents](https://console.aws.amazon.com/bedrock/home?#/agents) page, select the agent you created.
2. Click **Create Alias**.
3. Enter an **Alias name** and **Description**.
4. Click **Create alias**.

#### Test the Bedrock agent

To test the newly created agent, use the playground on the right of the screen when we open the agent.

In this example, we used a dataset of research papers for our source data. We can ask a question about those papers and retrieve a detailed response, this time with the deployed version.

<img alt="" />

By inspecting the trace, we can see what chunks were used by the Agent and diagnose issues with responses.

<img alt="" />

## Related articles

* [Pinecone as a Knowledge Base for Amazon Bedrock](https://www.pinecone.io/blog/amazon-bedrock-integration/)


# Amazon SageMaker
Source: https://docs.pinecone.io/integrations/amazon-sagemaker

Combine Amazon SageMaker with Pinecone to host LLMs and embedding models for scalable retrieval augmented generation and vector search workloads.

Amazon SageMaker is a fully managed service that brings together a broad set of tools to enable high-performance, low-cost machine learning (ML) for any use case. With SageMaker, you can build, train and deploy ML models at scale-- all in one integrated development environment (IDE). SageMaker supports governance requirements with simplified access control and transparency over your ML projects. Amazon SageMaker offers access to hundreds of pretrained models, including publicly available foundational models (FMs), and you can build your own FMs with purpose-built tools to fine-tune, experiment, retrain, and deploy FMs.

Amazon SageMaker and Pinecone can be used together for high-performance, scalable, and reliable retrieval augmented generation (RAG) use cases. The integration uses Amazon SageMaker to compute and host models for large language Models (LLMs), and uses Pinecone as the knowledge base that keeps the LLMs up-to-date with the latest information, reducing the likelihood of hallucinations.

<PrimarySecondaryCTA />

## Related articles

* [Mitigate hallucinations through Retrieval Augmented Generation using Pinecone vector database & Llama-2 from Amazon SageMaker JumpStart](https://aws.amazon.com/blogs/machine-learning/mitigate-hallucinations-through-retrieval-augmented-generation-using-pinecone-vector-database-llama-2-from-amazon-sagemaker-jumpstart/)


# Anyscale
Source: https://docs.pinecone.io/integrations/anyscale

Pair Anyscale Endpoints with Canopy and Pinecone to build RAG apps on managed open-source LLMs, with vector search and semantic retrieval out of the box.

Anyscale Endpoints offers open-source large language models (LLMs) as fully managed API endpoints. This allows you to focus on building applications powered by LLMs without the need to worry about the underlying infrastructure.

Use Anyscale Endpoints with Canopy, an open source SDK that allows you to test, build, and package retrieval augmented generation (RAG) applications with Pinecone vector database.

<PrimarySecondaryCTA />


# AWS Marketplace
Source: https://docs.pinecone.io/integrations/aws-marketplace

Subscribe to Pinecone through AWS Marketplace for centralized procurement, pay-as-you-go billing, and consolidated invoicing on your AWS account.

Access Pinecone through our AWS Marketplace listing. AWS Marketplace allows you to manage Pinecone and other third-party software from a centralized location, and simplifies software licensing and procurement with flexible pricing options and multiple deployment methods.

You can set up pay-as-you-go billing for a Pinecone organization through the AWS Marketplace.

<PrimarySecondaryCTA />


# Attribute usage to your integration
Source: https://docs.pinecone.io/integrations/build-integration/attribute-usage-to-your-integration

Attribute Pinecone SDK and REST usage to your integration with source tags and User-Agent values so support and analytics can trace traffic to your product.

Once you have created your integration with Pinecone, specify a **source tag** when instantiating clients with Pinecone SDKs, or pass a source tag as part of the `User-Agent` header when using the API directly.

<Note>
  Anyone can create an integration, but [becoming an official Pinecone partner](/integrations/build-integration/integration-ecosystem) can help accelerate your go-to-market and add value to your customers.
</Note>

### Source tag naming conventions

Your source tag must follow these conventions:

* Clearly identify your integration.
* Use only lowercase letters, numbers, underscores, and colons.

For example, for an integration called "New Framework", `"new_framework"` is valid, but `"new framework"` and `"New_framework"` are not valid.

### Specify a source tag

| Pinecone SDK                              | Required version |
| ----------------------------------------- | ---------------- |
| [Python](/reference/sdks/python/overview) | v3.2.1+          |
| [Node.js](/reference/sdks/node/overview)  | v2.2.0+          |
| [Java](/reference/sdks/java/overview)     | v1.0.0+          |
| [Go](/reference/sdks/go/overview)         | v0.4.1+          |

<CodeGroup>
  ```python Python theme={null}
  # REST client
  from pinecone import Pinecone

  pc = Pinecone(
      api_key="YOUR_API_KEY", 
      source_tag="YOUR_SOURCE_TAG"
  )

  # gRPC client
  from pinecone.grpc import PineconeGRPC

  pc = PineconeGRPC(
      api_key="YOUR_API_KEY", 
      source_tag="YOUR_SOURCE_TAG"
  )
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone';

  const pc = new Pinecone({ 
      apiKey: 'YOUR_API_KEY', 
      sourceTag: 'YOUR_SOURCE_TAG' 
  });
  ```

  ```java Java theme={null}
  import io.pinecone.clients.Pinecone;

  public class IntegrationExample {
      public static void main(String[] args) {
          Pinecone pc = new Pinecone.Builder("YOUR_API_KEY")
                  .withSourceTag("YOUR_SOURCE_TAG")
                  .build();
      }
  }
  ```

  ```go Go theme={null}
  import "github.com/pinecone-io/go-pinecone/v4/pinecone"

  client, err := pinecone.NewClient(pinecone.NewClientParams{
  	ApiKey: "YOUR_API_KEY",
  	SourceTag: "YOUR_SOURCE_TAG",
  })
  ```

  ```shell curl theme={null}
  curl -i -X GET "https://api.pinecone.io/indexes" \
    -H "Accept: application/json" \
    -H "Api-Key: YOUR_API_KEY" \
    -H "User-Agent: source_tag=YOUR_SOURCE_TAG" \
    -H "X-Pinecone-Api-Version: 2025-10"
  ```
</CodeGroup>


# Connect your users to Pinecone
Source: https://docs.pinecone.io/integrations/build-integration/connect-your-users-to-pinecone

Embed a Connect to Pinecone flow in your app or notebook so users can sign in, choose a project, and receive an API key without leaving your integration.

To reduce friction for users using your integration, you can create a [custom object](#custom-object), like a button or link, to trigger a **Connect to Pinecone** popup from your app, website, or [Colab](https://colab.google/) notebook. Within this popup, your users can sign up for or log in to Pinecone, select or create an organization and project to connect to, and generate an API key. The API key is then communicated back to the user to copy or directly sent to the hosting page, app, or notebook.

Alternatively, you can embed our [pre-built widget](#pre-built-widget), which provides the same functionality, but with the ease of a drop-in component.

To start, [create an integration ID](#create-an-integration-id) for your app.

<Note>
  Only [organization owners](/guides/organizations/manage-organization-members) can add or manage integrations.
</Note>

## Create an integration ID

Create a unique `integrationId` to enable usage of the **Connect to Pinecone** [popup](#custom-object) and [widget](#pre-built-widget):

1. On the the [**Integrations**](https://app.pinecone.io/organizations/-/settings/integrations) tab in the Pinecone console, click the **Create Integration** button.

   <Note>The **Integrations** tab does not display unless your organization already has integrations. [Follow this link to create your first integration](https://app.pinecone.io/organizations/-/settings/integrations?create=true).</Note>

2. Fill out the **Create integration** form:
   * **Integration name**: Give your integration a name.

   * **URL Slug**: This is your `integrationID`. Enter a human-readable string that uniquely identifies your integration and that may appear in URLs. Your integration URL slug is public and cannot be changed.

   * **Logo**: Upload a logo for your integration.

   * **Return mechanism**: Select one of the following return methods for the generated API key:
     * **Web Message**: Your application will receive the Pinecone API key via a web message. Select this option if you are using the [@pinecone-database/connect library](/integrations/build-integration/connect-your-users-to-pinecone#javascript). The API key will only be provided to the allowed origin(s) specified below.
     * **Copy/Paste**: The API key will display in the success message, and users will need to copy and paste their Pinecone API keys into your application.

   * **Allowed origin**: If you selected **Web Message** as your **Return mechanism**, list the URL origin(s) where your integration is hosted. The [origin](https://developer.mozilla.org/en-US/docs/Glossary/Origin) is the part of the URL that specifies the protocol, hostname, and port.

3. Click **Create**.

<Note>
  Anyone can create an integration, but [becoming an official Pinecone partner](/integrations/build-integration/integration-ecosystem) can help accelerate your go-to-market and add value to your customers.
</Note>

## Custom object

[Once you have created your `integrationId`](#create-an-integration-id), you can create a custom object, like a button or link, that loads a **Connect to Pinecone** popup that displays as follows:

<img alt="Connect popup" />

The `ConnectPopup` function can be called with either the JavaScript library or script. The JavaScript library is the most commonly used method, but the script can be used in instances where you cannot build and use a custom library, like within the constraints of a content management system (CMS).

The function includes the following **required** configuration option:

* `integrationId`: The slug assigned to the integration. If `integrationId` is not passed, the widget will not render.

  <Note>To create a unique `integrationId`, fill out the [Create Integration form](#create-an-integration-id).</Note>

The function returns an object containing the following:

* `open`: A function that opens the popup. Suitable for use as an on-click handler.

Example usage of the library and script:

<CodeGroup>
  ```javascript JavaScriptlibrary theme={null}
  import { ConnectPopup } from '@pinecone-database/connect'

  /*  Define a function called connectWithAPIKey */
  const connectWithAPIKey = () => {
    return new Promise((resolve, reject) => {
      /* Call ConnectPopup function with an object containing options */
      const popup = ConnectPopup({
        onConnect: (key) => {
          resolve(key);
        },
        integrationId: 'myApp'
      }).open();
    });
  };

  /* Handle button click event */
  document.getElementById('connectButton').addEventListener('click', () => {
    connectWithAPIKey()
      .then(apiKey => {
        console.log("API Key:", apiKey);
      })
      .catch(error => {
        console.error("Error:", error);
      });
  });
  ```

  ```html JavaScript script theme={null}
  <head>
  ...
  <script src="https://connect.pinecone.io/embed.js"></script>
  <script>
    const pineconePopup = ConnectPopup({
      onConnect: (key) => console.log(key),
      onCancel: () => console.log("Cancelled"),
      integrationId: 'myApp'
    });
  </script>
  ...
  </head>
  <body>
  ...
  <button onclick="pineconePopup.open()">Connect to Pinecone!</button>
  ...
  </body>
  ```
</CodeGroup>

Once you have created your integration, be sure to [attribute usage to your integration](/integrations/build-integration/attribute-usage-to-your-integration).

## Pre-built widget

The pre-built **Connect** widget displays as follows:

<img alt="Connect widget" />

[Once you have created your `integrationId`](#create-an-integration-id), you can embed the **Connect** widget multiple ways:

* [JavaScript](#javascript) library (`@pinecone-database/connect`) or script: Renders the widget in apps and websites.
* [Colab](#colab) (`pinecone-notebooks`): Renders the widget in Colab notebooks using Python.

Once you have created your integration, be sure to [attribute usage to your integration](/integrations/build-integration/attribute-usage-to-your-integration).

### JavaScript

To embed the **Connect to Pinecone** widget in your app or website using the [`@pinecone-database/connect` library](https://www.npmjs.com/package/@pinecone-database/connect), install the necessary dependencies:

```shell Shell theme={null}
# Install dependencies
npm i -S @pinecone-database/connect
```

You can use the JavaScript library to render the **Connect to Pinecone** widget and obtain the API key with the [`connectToPinecone` function](#connecttopinecone-function). It displays the widget and calls the provided callback function with the Pinecone API key, once the user completes the flow.

The function includes the following **required** configuration options:

* `integrationId`: The slug assigned to the integration. If `integrationId` is not passed, the widget will not render.

  <Note>To create a unique `integrationId`, [fill out the Create Integration form](#create-an-integration-id) with Pinecone.</Note>

* `container`: The HTML element where the **Connect** widget will render.

Example usage:

```JavaScript JavaScript theme={null}
import {connectToPinecone} from '@pinecone-database/connect'

const setupPinecone = (apiKey) => { /* Set up a Pinecone client using the API key */ }

connectToPinecone(
  setupPinecone,
  {
    integrationId: 'myApp',
    container: document.getElementById('connect-widget')
  }
)
```

If you cannot use the JavaScript library, you can directly call the script. For example:

```html HTML theme={null}
<head>
  ...
  <script src="https://connect.pinecone.io/embed.js">
  ...
</head>
<body>

<div id="widgetContainer"></div>
...

<script>
  connectToPinecone(
    (apiKey) => {/* Use the apiKey to create an index*/},
    {
      integrationId: 'myApp',
      container: document.getElementById('widgetContainer'),
    }
  );
</script>

...
</body>
```

### Colab

To embed the **Connect** widget in your Colab notebook, use the [`pinecone-notebooks` Python library](https://pypi.org/project/pinecone-notebooks/#description):

```shell theme={null}
# Install dependencies using Colab syntax

pip install -qU pinecone-notebooks pinecone[grpc]
```

```python theme={null}
# Render the Connect widget for the user to authenticate and generate an API key

from pinecone_notebooks.colab import Authenticate

Authenticate()

# The generated API key is available in the PINECONE_API_KEY environment variable

from pinecone.grpc import PineconeGRPC as Pinecone
from pinecone import ServerlessSpec
import os

api_key = os.environ.get('PINECONE_API_KEY')

# Use the API key to initialize the Pinecone client
pc = Pinecone(api_key=api_key)
```

<Tip>
  To see this flow in practice, see our [example notebook](https://colab.research.google.com/drive/1VZ-REFRbleJG4tfJ3waFIrSveqrYQnNx?usp=sharing).
</Tip>

## Manage generated API keys

Your users can [manage the API keys](/guides/projects/manage-api-keys) generated by your integration in the Pinecone console.


# Integration ecosystem
Source: https://docs.pinecone.io/integrations/build-integration/integration-ecosystem

How Pinecone integrations are built with public SDKs and APIs and how listings on the Integrations hub are reviewed for partner support and quality.

Anyone can use the [Pinecone SDKs](/reference/pinecone-sdks) or the [Pinecone API](/reference/api/introduction) to build a native Pinecone integration. We encourage you to build and launch freely to support your users.

Listing on our official [Integrations](/integrations/overview) page is a curated process. We prioritize applications from integrations that are actively used by mutual customers. If you believe your integration qualifies for official partner support, please fill out our [application form](https://dash.partnerstack.com/application?company=pinecone\&group=technologypartners).

## Additional information

* [Attribute usage to your integration](/integrations/build-integration/attribute-usage-to-your-integration)
* [Connect your users to Pinecone](/integrations/build-integration/connect-your-users-to-pinecone)


# Cloudera AI
Source: https://docs.pinecone.io/integrations/cloudera

Integrate Cloudera AI with Pinecone to run distributed Spark and Python embedding pipelines and power scalable RAG and vector search on enterprise data.

[Cloudera AI](https://www.cloudera.com/) is an enterprise data cloud experience that provides scalable, secure, and agile machine learning and AI workflows. It leverages the power of Python, Apache Spark, R, and a host of other runtimes for distributed data processing, enabling the efficient creation, ingestion, and updating of vector embeddings at scale.

The primary advantage of Cloudera AI lies in its integration with the Cloudera ecosystem, which facilitates seamless data flow and processing across various stages of machine learning and AI pipelines. Cloudera AI offers interactive sessions, collaborative projects, model hosting capabilities, and application hosting features, all within a Python-centric development environment. This multifaceted approach enables users to efficiently develop, train, and deploy machine learning and AI models at scale.

Integrating Pinecone with Cloudera AI elevates the potential of Retrieval-Augmented Generation (RAG) models by providing a robust, scalable vector search platform. Pinecone's strength in handling vector embeddings — characterized by its ultra-low query latency, dynamic index updates, and scalability to billions of vector embeddings — make it the perfect match for the nuanced needs of RAG applications built on Cloudera AI.

Within the Cloudera AI ecosystem, Pinecone acts as a first-class citizen for RAG by efficiently retrieving relevant context from massive datasets, enhancing the generation capabilities of models with relevant, real-time data. This integration enables the development of sophisticated machine learning and AI applications that combine the predictive power of Cloudera AI's hosted models with the dynamic retrieval capabilities of Pinecone, offering unparalleled accuracy and relevance for generated outputs. By leveraging Cloudera AI's project and session management features, developers can prototype, develop, and deploy these complex systems more effectively, making advanced machine learning and AI applications more accessible and practical for enterprise use.

Cloudera's Accelerators for Machine Learning Projects (AMPs) drive efficient deployment of RAG architectures by doing the development work for you. This AMP serves as a prototype for fully integrating Pinecone into a RAG use case and illustrates semantic search with RAG at scale.

<PrimarySecondaryCTA />

## Additional resources

* [Python script](https://github.com/cloudera/CML_llm-hol/blob/main/2_populate_vector_db/pinecone_vectordb_insert.py) - Example of creating vectors in Pinecone
* [Jupyter notebook](https://github.com/cloudera/CML_llm-hol/blob/main/3_query_vector_db/pinecone_vectordb_query.ipynb) - Example of querying Pinecone collections


# Cohere
Source: https://docs.pinecone.io/integrations/cohere

Connect Pinecone and Cohere to ship vector search and RAG applications: generate Cohere embeddings, index them in Pinecone, and rerank results.

The Cohere platform builds natural language processing and generation into your product with a few lines of code. Cohere's large language models (LLMs) can solve a broad spectrum of natural language use cases, including classification, semantic search, paraphrasing, summarization, and content generation.

Use the Cohere Embed API endpoint to generate language embeddings, and then index those embeddings in the Pinecone vector database for fast and scalable vector search.

<PrimarySecondaryCTA />

## Setup guide

[View source](https://github.com/pinecone-io/examples/blob/master/integrations/cohere/)

[Open in Colab](https://colab.research.google.com/github/pinecone-io/examples/blob/master/integrations/cohere/semantic%5Fsearch%5Ftrec.ipynb)

In this guide, you will learn how to use the [Cohere Embed API endpoint](https://docs.cohere.ai/reference/embed) to generate language embeddings, and then index those embeddings in the [Pinecone vector database](https://www.pinecone.io) for fast and scalable vector search.

This is a powerful and common combination for building semantic search, question-answering, threat-detection, and other applications that rely on NLP and search over a large corpus of text data.

The basic workflow looks like this:

* Embed and index
  * Use the Cohere Embed API endpoint to generate vector embeddings of your documents (or any text data).
  * Upload those vector embeddings into Pinecone, which can store and index millions/billions of these vector embeddings, and search through them at ultra-low latencies.
* Search
  * Pass your query text or document through the Cohere Embed API endpoint again.
  * Take the resulting vector embedding and send it as a [query](/guides/search/search-overview) to Pinecone.
  * Get back semantically similar documents, even if they don't share any keywords with the query.

<img alt="Basic workflow of Cohere with Pinecone" />

### Set up the environment

Start by installing the Cohere and Pinecone clients and HuggingFace *Datasets* for downloading the TREC dataset used in this guide:

```shell Shell theme={null}
pip install -U cohere pinecone datasets
```

### Create embeddings

Sign up for an API key at [Cohere](https://dashboard.cohere.com/api-keys) and then use it to initialize your connection.

```Python Python theme={null}
import cohere

co = cohere.Client("<YOUR_API_KEY>")
```

Load the **T**ext **RE**trieval **C**onference (TREC) question classification dataset, which contains 5.5K labeled questions. You will take only the first 1K samples for this walkthrough, but this can be scaled to millions or even billions of samples.

```Python Python theme={null}
from datasets import load_dataset

# load the first 1K rows of the TREC dataset
trec = load_dataset('trec', split='train[:1000]')
```

Each sample in `trec` contains two label features and the *text* feature. Pass the questions from the *text* feature to Cohere to create embeddings.

```Python Python theme={null}
embeds = co.embed(
    texts=trec['text'],
    model='embed-english-v3.0',
    input_type='search_document',
    truncate='END'
).embeddings
```

Check the dimensionality of the returned vectors. You will need to save the embedding dimensionality from this to be used when initializing your Pinecone index later

```Python Python theme={null}
import numpy as np

shape = np.array(embeds).shape
print(shape)

# [Out]:
# (1000, 1024)
```

You can see the `1024` embedding dimensionality produced by Cohere's `embed-english-v3.0` model, and the `1000` samples you built embeddings for.

### Store the Embeddings

Now that you have your embeddings, you can move on to indexing them in the Pinecone vector database. For this, you need a [Pinecone API key](/guides/projects/manage-api-keys).

You first initialize our connection to Pinecone and then create a new index called `cohere-pinecone-trec` for storing the embeddings. When creating the index, you specify that you would like to use the cosine similarity metric to align with Cohere's embeddings, and also pass the embedding dimensionality of `1024`.

```Python Python theme={null}
from pinecone import Pinecone

# initialize connection to pinecone (get API key at app.pinecone.io)
pc = Pinecone(api_key='YOUR_API_KEY')

index_name = 'cohere-pinecone-trec'

# if the index does not exist, we create it
if not pc.has_index(index_name):
    pc.create_index(
        name=index_name,
        dimension=shape[1],
        metric="cosine",
        spec=ServerlessSpec(
            cloud='aws', 
            region='us-east-1'
        ) 
    )

# connect to index
index = pc.Index(index_name)
```

Now you can begin populating the index with your embeddings. Pinecone expects you to provide a list of tuples in the format *(id, vector, metadata)*, where the *metadata* field is an optional extra field where you can store anything you want in a dictionary format. For this example, you will store the original text of the embeddings.

While uploading your data, you will batch everything to avoid pushing too much data in one go.

```Python Python theme={null}
batch_size = 128

ids = [str(i) for i in range(shape[0])]
# create list of metadata dictionaries
meta = [{'text': text} for text in trec['text']]

# create list of (id, vector, metadata) tuples to be upserted
to_upsert = list(zip(ids, embeds, meta))

for i in range(0, shape[0], batch_size):
    i_end = min(i+batch_size, shape[0])
    index.upsert(vectors=to_upsert[i:i_end])

# let's view the index statistics
print(index.describe_index_stats())

# [Out]:
# {'dimension': 1024,
#  'index_fullness': 0.0,
#  'namespaces': {'': {'vector_count': 1000}},
#  'total_vector_count': 1000}
```

You can see from `index.describe_index_stats` that you have a *1024-dimensionality* index populated with *1000* embeddings. For serverless on-demand indexes, the `index_fullness` metric is typically `0` because storage and compute scale automatically. If you're using [dedicated read nodes](/guides/index-data/dedicated-read-nodes#index-fullness), `index_fullness` (along with `memory_fullness` and `storage_fullness`) tells you how close the index is to its allocated capacity.

### Semantic search

Now that you have your indexed vectors, you can perform a few search queries. When searching, you will first embed your query using Cohere, and then search using the returned vector in Pinecone.

```Python Python theme={null}
query = "What caused the 1929 Great Depression?"

# create the query embedding
xq = co.embed(
    texts=[query],
    model='embed-english-v3.0',
    input_type='search_query',
    truncate='END'
).embeddings

print(np.array(xq).shape)

# query, returning the top 5 most similar results
res = index.query(vector=xq, top_k=5, include_metadata=True)
```

The response from Pinecone includes your original text in the `metadata` field. Let's print out the `top_k` most similar questions and their respective similarity scores.

```Python Python theme={null}
for match in res['matches']:
    print(f"{match['score']:.2f}: {match['metadata']['text']}")

# [Out]:
# 0.62: Why did the world enter a global depression in 1929 ?
# 0.49: When was `` the Great Depression '' ?
# 0.38: What crop failure caused the Irish Famine ?
# 0.32: What caused Harry Houdini 's death ?
# 0.31: What causes pneumonia ?
```

Looks good! Let's make it harder and replace *"depression"* with the incorrect term *"recession"*.

```Python Python theme={null}
query = "What was the cause of the major recession in the early 20th century?"

# create the query embedding
xq = co.embed(
    texts=[query],
    model='embed-english-v3.0',
    input_type='search_query',
    truncate='END'
).embeddings

# query, returning the top 5 most similar results
res = index.query(vector=xq, top_k=5, include_metadata=True)

for match in res['matches']:
    print(f"{match['score']:.2f}: {match['metadata']['text']}")

# [Out]:
# 0.43: When was `` the Great Depression '' ?
# 0.40: Why did the world enter a global depression in 1929 ?
# 0.39: When did World War I start ?
# 0.35: What are some of the significant historical events of the 1990s ?
# 0.32: What crop failure caused the Irish Famine ?
```

Let's perform one final search using the definition of depression rather than the word or related words.

```Python Python theme={null}
query = "Why was there a long-term economic downturn in the early 20th century?"

# create the query embedding
xq = co.embed(
    texts=[query],
    model='embed-english-v3.0',
    input_type='search_query',
    truncate='END'
).embeddings

# query, returning the top 10 most similar results
res = index.query(vector=xq, top_k=10, include_metadata=True)

for match in res['matches']:
    print(f"{match['score']:.2f}: {match['metadata']['text']}")

# [Out]:
# 0.40: When was `` the Great Depression '' ?
# 0.39: Why did the world enter a global depression in 1929 ?
# 0.35: When did World War I start ?
# 0.32: What are some of the significant historical events of the 1990s ?
# 0.31: What war did the Wanna-Go-Home Riots occur after ?
# 0.31: What do economists do ?
# 0.29: What historical event happened in Dogtown in 1899 ?
# 0.28: When did the Dow first reach ?
# 0.28: Who earns their money the hard way ?
# 0.28: What were popular songs and types of songs in the 1920s ?
```

It's clear from this example that the semantic search pipeline is clearly able to identify the meaning between each of your queries. Using these embeddings with Pinecone allows you to return the most semantically similar questions from the already indexed TREC dataset.


# Context Data
Source: https://docs.pinecone.io/integrations/context-data

Use Context Data with Pinecone to build no-code flows from Postgres, S3, Salesforce, and more, embedding data and querying indexes in Query Studio.

Using [Context Data](https://contextdata.ai/), you can easily create end-to-end data flows by connecting to a myriad of data sources (PostgreSQL, MySQL, Amazon S3, Salesforce, etc.), seamlessly embedding and writing the results to Pinecone using Context Data's super simple no-code web interface. These flows can also be configured to be triggered and run on a user-defined schedule.

Additionally, Context Data provides the ability to create transformations like aggregations, joins, and feature engineering using SQL common table expressions before writing to Pinecone.

You also have the ability to "chat" with your Pinecone indexes directly from Context Data's privacy-focused Query Studio.

<PrimarySecondaryCTA />


# Datadog
Source: https://docs.pinecone.io/integrations/datadog

Monitor Pinecone with the Datadog integration to track request latency, index fullness, and usage trends, and alert on anomalies in vector workloads.

<Note>
  This feature is available on the [Builder, Standard, and Enterprise plans](https://www.pinecone.io/pricing/).
</Note>

Datadog is a monitoring and analytics tool that can be used to determine performance metrics as well as event monitoring for infrastructure and cloud services. Use Datadog to:

* Optimize performance and control usage: Observe and track specific actions (e.g., request count) within Pinecone to identify application requests with high latency or usage. Monitor trends and gain actionable insights to improve resource utilization and reduce spend.
* Automatically alert on metrics: Get alerted when index fullness reaches a certain threshold. You can also create your own customized monitors to alert on specific metrics and thresholds.
* Locate and triage unexpected spikes in usage or latency: Quickly visualize anomalies in usage or latency in Pinecone's Datadog dashboard. View metrics over time to better understand trends and determine the severity of a spike.

<PrimarySecondaryCTA />

## Setup guide

Follow these steps to monitor a Pinecone project with Datadog:

1. Go to the [Pinecone integration](https://app.datadoghq.com/integrations/pinecone) tile in Datadog.
2. Go to the **Configure** tab.
3. Click **+ Add New**.
4. Enter a project name to identify your project in Datadog.
5. Do not select an environment. This is a legacy setting.
6. Enter an [API key](/guides/projects/understanding-projects#api-keys) for the Pinecone project you want to monitor.
7. Enter the [project ID](/guides/projects/understanding-projects#project-ids) of the Pinecone project you want to monitor.
8. Save the configuration.

On the **Monitoring Resources** tab, you'll find dashboards for the pod-based and serverless indexes in your project and recommendations for [configuring monitors](https://docs.datadoghq.com/monitors/configuration/?tab=thresholdalert) using [Pinecone's metrics](/guides/production/monitoring#available-metrics).


# Genkit
Source: https://docs.pinecone.io/integrations/genkit

Use the Genkit Pinecone plugin with Firebase to build AI features with type-safe indexers, embedders, and retrievers for RAG and semantic search apps.

The [Genkit](https://firebase.google.com/docs/genkit) Pinecone plugin empowers developers to reduce the complexity of integrating AI components through simple indexers, embedders and retrievers abstractions. Through the Genkit Pinecone plugin, developers can integrate AI models with their own custom logic and data to build AI features optimized for their businesses.

Additionally, developers can analyze unstructured text, generate creative content, select tasks, and send results back to their app as structured type-safe objects.
The plugin provides a common format for content that supports combinations of text, data, and other media. Developers can use Genkit for models that perform any generative task (such as image generation), not just LLMs.

<PrimarySecondaryCTA />


# GitHub Copilot
Source: https://docs.pinecone.io/integrations/github-copilot

Install the Pinecone GitHub Copilot Extension to query your indexes, get coding assistance for the Pinecone API, and debug RAG apps from your editor.

Access the Pinecone Copilot Extension through our GitHub Marketplace listing. The Pinecone Copilot Extension serves as a seamless bridge between you and your Pinecone data-- providing product information, coding assistance, troubleshooting capabilities and streamlining the debugging process.

This extension offers personalized recommendations right to your fingertips, enabling you to swiftly retrieve relevant data and collaborate effectively with Copilot.

<PrimarySecondaryCTA />


# Google Cloud Marketplace
Source: https://docs.pinecone.io/integrations/google-cloud-marketplace

Subscribe to Pinecone through Google Cloud Marketplace for centralized procurement, pay-as-you-go billing, and consolidated GCP invoicing.

Access Pinecone through our Google Cloud Marketplace listing. Google Cloud Marketplace allows you to manage Pinecone and other third-party software from a centralized location, and simplifies software licensing and procurement with flexible pricing options and multiple deployment methods.

You can set up pay-as-you-go billing for a Pinecone organization through the Google Cloud Marketplace.

<PrimarySecondaryCTA />


# Haystack
Source: https://docs.pinecone.io/integrations/haystack

Use Deepset Haystack's PineconeDocumentStore to build production NLP pipelines that index, embed, and query documents for question answering and RAG.

Haystack is the open source Python framework by Deepset for building custom apps with large language models (LLMs). It lets you quickly try out the latest models in natural language processing (NLP) while being flexible and easy to use. Their community of users and builders has helped shape Haystack into what it is today: a complete framework for building production-ready NLP apps.

Haystack and Pinecone integration can be used to keep your NLP-driven apps up-to-date with Haystack's indexing pipelines that help you prepare and maintain your data.

<PrimarySecondaryCTA />

## Setup guide

In this guide we will see how to integrate Pinecone and the popular [Haystack library](https://github.com/deepset-ai/haystack) for *Question-Answering*.

### Install Haystack

We start by installing the latest version of Haystack with all dependencies required for the `PineconeDocumentStore`.

```Python Python theme={null}
pip install -U farm-haystack>=1.3.0 pinecone[grpc] datasets
```

### Initialize the PineconeDocumentStore

We initialize a `PineconeDocumentStore` by providing an API key and environment name. [Create an account](https://app.pinecone.io) to get your free API key.

```Python Python theme={null}
from haystack.document_stores import PineconeDocumentStore

document_store = PineconeDocumentStore(
    api_key='<YOUR_API_KEY>',
    index='haystack-extractive-qa',
    similarity="cosine",
    embedding_dim=384
)
```

```
INFO - haystack.document_stores.pinecone -  Index statistics: name: haystack-extractive-qa, embedding dimensions: 384, record count: 0
```

### Prepare data

Before adding data to the document store, we must download and convert data into the Document format that Haystack uses.

We will use the SQuAD dataset available from Hugging Face Datasets.

```Python Python theme={null}
from datasets import load_dataset

# load the squad dataset
data = load_dataset("squad", split="train")
```

Next, we remove duplicates and unecessary columns.

```Python Python theme={null}
# convert to a pandas dataframe
df = data.to_pandas()
# select only title and context column
df = df[["title", "context"]]
# drop rows containing duplicate context passages
df = df.drop_duplicates(subset="context")
df.head()
```

| title | context                     |                                                   |
| ----- | --------------------------- | ------------------------------------------------- |
| 0     | University\_of\_Notre\_Dame | Architecturally, the school has a Catholic cha... |
| 5     | University\_of\_Notre\_Dame | As at most other universities, Notre Dame's st... |
| 10    | University\_of\_Notre\_Dame | The university is the major seat of the Congre... |
| 15    | University\_of\_Notre\_Dame | The College of Engineering was established in ... |
| 20    | University\_of\_Notre\_Dame | All of Notre Dame's undergraduate students are... |

Then convert these records into the Document format.

```Python Python theme={null}
from haystack import Document

docs = []
for d in df.iterrows():
    d = d[1]
    # create haystack document object with text content and doc metadata
    doc = Document(
        content=d["context"],
        meta={
            "title": d["title"],
            'context': d['context']
        }
    )
    docs.append(doc)
```

This `Document` format contains two fields; *'content'* for the text content or paragraphs, and *'meta'* where we can place any additional information that can later be used to apply metadata filtering in our search.

Now we upsert the documents to Pinecone.

```Python Python theme={null}
# upsert the data document to pinecone index
document_store.write_documents(docs)
```

### Initialize retriever

The next step is to create embeddings from these documents. We will use Haystacks `EmbeddingRetriever` with a SentenceTransformer model (`multi-qa-MiniLM-L6-cos-v1`) which has been designed for question-answering.

```Python Python theme={null}
from haystack.retriever.dense import EmbeddingRetriever

retriever = EmbeddingRetriever(
    document_store=document_store,
    embedding_model="multi-qa-MiniLM-L6-cos-v1",
    model_format="sentence_transformers"
)
```

Then we run the `PineconeDocumentStore.update_embeddings` method with the `retriever` provided as an argument. GPU acceleration can greatly reduce the time required for this step.

```Python Python theme={null}
document_store.update_embeddings(
    retriever,
    batch_size=16
)
```

### Inspect documents and embeddings

We can get documents by their ID with the `PineconeDocumentStore.get_documents_by_id` method.

```Python Python theme={null}
d = document_store.get_documents_by_id(ids=['49091c797d2236e73fab510b1e9c7f6b'], return_embedding=True)[0]
```

From here we return can view document content with `d.content` and the document embedding with `d.embedding`.

### Initialize an extractive QA pipeline

An `ExtractiveQAPipeline` contains three key components by default:

* a document store (`PineconeDocumentStore`)
* a retriever model
* a reader model

We use the `deepset/electra-base-squad2` model from the HuggingFace model hub as our reader model.

```Python Python theme={null}
from haystack.nodes import FARMReader

reader = FARMReader(
    model_name_or_path='deepset/electra-base-squad2', 
    use_gpu=True
)
```

We are now ready to initialize the `ExtractiveQAPipeline`.

```Python Python theme={null}
from haystack.pipelines import ExtractiveQAPipeline

pipe = ExtractiveQAPipeline(reader, retriever)
```

### Ask Questions

Using our QA pipeline we can begin querying with `pipe.run`.

```Python Python theme={null}
from haystack.utils import print_answers

query = "What was Albert Einstein famous for?"
# get the answer
answer = pipe.run(
    query=query,
    params={
        "Retriever": {"top_k": 1},
    }
)
# print the answer(s)
print_answers(answer)
```

```
Inferencing Samples: 100%|██████████| 1/1 [00:00<00:00,  3.53 Batches/s]

Query: What was Albert Einstein famous for?
Answers:
[   <Answer {
    'answer': 'his theories of special relativity and general relativity', 'type': 'extractive', 'score': 0.993550717830658,
    'context': 'Albert Einstein is known for his theories of special relativity and general relativity. He also made important contributions to statistical mechanics,',
    'offsets_in_document': [{'start': 29, 'end': 86}],
    'offsets_in_context': [{'start': 29, 'end': 86}], 
    'document_id': '23357c05e3e46bacea556705de1ea6a5',
    'meta': {
        'context': 'Albert Einstein is known for his theories of special relativity and general relativity. He also made important contributions to statistical mechanics, especially his mathematical treatment of Brownian motion, his resolution of the paradox of specific heats, and his connection of fluctuations and dissipation. Despite his reservations about its interpretation, Einstein also made contributions to quantum mechanics and, indirectly, quantum field theory, primarily through his theoretical studies of the photon.', 'title': 'Modern_history'
    }
}>]
```

```Python Python theme={null}
query = "How much oil is Egypt producing in a day?"
# get the answer
answer = pipe.run(
    query=query,
    params={
        "Retriever": {"top_k": 1},
    }
)
# print the answer(s)
print_answers(answer)
```

```
Inferencing Samples: 100%|██████████| 1/1 [00:00<00:00,  3.81 Batches/s]

Query: How much oil is Egypt producing in a day?
Answers:
[   <Answer {
    'answer': '691,000 bbl/d', 'type': 'extractive', 'score': 0.9999906420707703,
    'context': 'Egypt was producing 691,000 bbl/d of oil and 2,141.05 Tcf of natural gas (in 2013), which makes Egypt as the largest oil producer not member of the Or',
    'offsets_in_document': [{'start': 20, 'end': 33}],
    'offsets_in_context': [{'start': 20, 'end': 33}],
    'document_id': '57ed9720050a17237e323da5e3969a9b',
    'meta': {
        'context': 'Egypt was producing 691,000 bbl/d of oil and 2,141.05 Tcf of natural gas (in 2013), which makes Egypt as the largest oil producer not member of the Organization of the Petroleum Exporting Countries (OPEC) and the second-largest dry natural gas producer in Africa. In 2013, Egypt was the largest consumer of oil and natural gas in Africa, as more than 20% of total oil consumption and more than 40% of total dry natural gas consumption in Africa. Also, Egypt possesses the largest oil refinery capacity in Africa 726,000 bbl/d (in 2012). Egypt is currently planning to build its first nuclear power plant in El Dabaa city, northern Egypt.', 'title': 'Egypt'
    }
}>]
```

```Python Python theme={null}
query = "What are the first names of the youtube founders?"
# get the answer
answer = pipe.run(
    query=query,
    params={
        "Retriever": {"top_k": 1},
    }
)
# print the answer(s)
print_answers(answer)
```

```
Inferencing Samples: 100%|██████████| 1/1 [00:00<00:00,  3.83 Batches/s]

Query: What are the first names of the youtube founders?
Answers:
[   <Answer {
    'answer': 'Hurley and Chen', 'type': 'extractive', 'score': 0.9998972713947296,
    'context': 'According to a story that has often been repeated in the media, Hurley and Chen developed the idea for YouTube during the early months of 2005, after ',
    'offsets_in_document': [{'start': 64, 'end': 79}],
    'offsets_in_context': [{'start': 64, 'end': 79}],
    'document_id': 'bd1cbd61ab617d840c5f295e21e80092',
    'meta': {
        'context': 'According to a story that has often been repeated in the media, Hurley and Chen developed the idea for YouTube during the early months of 2005, after they had experienced difficulty sharing videos that had been shot at a dinner party at Chen\'s apartment in San Francisco. Karim did not attend the party and denied that it had occurred, but Chen commented that the idea that YouTube was founded after a dinner party "was probably very strengthened by marketing ideas around creating a story that was very digestible".', 'title': 'YouTube'
    }
}>]
```

We can return multiple answers by setting the `top_k` parameter.

```Python Python theme={null}
query = "Who was the first person to step foot on the moon?"
# get the answer
answer = pipe.run(
    query=query,
    params={
        "Retriever": {"top_k": 3},
    }
)
# print the answer(s)
print_answers(answer)
```

```
Inferencing Samples: 100%|██████████| 1/1 [00:00<00:00,  3.71 Batches/s]
Inferencing Samples: 100%|██████████| 1/1 [00:00<00:00,  3.78 Batches/s]
Inferencing Samples: 100%|██████████| 1/1 [00:00<00:00,  3.88 Batches/s]

Query: Who was the first person to step foot on the moon?
Answers:
[   <Answer {
    'answer': 'Armstrong', 'type': 'extractive', 'score': 0.9998227059841156, 
    'context': 'The trip to the Moon took just over three days. After achieving orbit, Armstrong and Aldrin transferred into the Lunar Module, named Eagle, and after ', 
    'offsets_in_document': [{'start': 71, 'end': 80}], 
    'offsets_in_context': [{'start': 71, 'end': 80}], 
    'document_id': 'f74e1bf667e68d72e45437a7895df921', 
    'meta': {
        'context': 'The trip to the Moon took just over three days. After achieving orbit, Armstrong and Aldrin transferred into the Lunar Module, named Eagle, and after a landing gear inspection by Collins remaining in the Command/Service Module Columbia, began their descent. After overcoming several computer overload alarms caused by an antenna switch left in the wrong position, and a slight downrange error, Armstrong took over manual flight control at about 180 meters (590 ft), and guided the Lunar Module to a safe landing spot at 20:18:04 UTC, July 20, 1969 (3:17:04 pm CDT). The first humans on the Moon would wait another six hours before they ventured out of their craft. At 02:56 UTC, July 21 (9:56 pm CDT July 20), Armstrong became the first human to set foot on the Moon.', 'title': 'Space_Race'
        }
    }>, <Answer {
    'answer': 'Frank Borman', 'type': 'extractive', 'score': 0.7770257890224457, 
    'context': 'On December 21, 1968, Frank Borman, James Lovell, and William Anders became the first humans to ride the Saturn V rocket into space on Apollo 8. They ', 
    'offsets_in_document': [{'start': 22, 'end': 34}], 
    'offsets_in_context': [{'start': 22, 'end': 34}], 
    'document_id': '2bc046ba90d94fe201ccde9d20552200', 
    'meta': {
        'context': "On December 21, 1968, Frank Borman, James Lovell, and William Anders became the first humans to ride the Saturn V rocket into space on Apollo 8. They also became the first to leave low-Earth orbit and go to another celestial body, and entered lunar orbit on December 24. They made ten orbits in twenty hours, and transmitted one of the most watched TV broadcasts in history, with their Christmas Eve program from lunar orbit, that concluded with a reading from the biblical Book of Genesis. Two and a half hours after the broadcast, they fired their engine to perform the first trans-Earth injection to leave lunar orbit and return to the Earth. Apollo 8 safely landed in the Pacific ocean on December 27, in NASA's first dawn splashdown and recovery.", 'title': 'Space_Race'
        }
    }>, <Answer {
    'answer': 'Aldrin', 'type': 'extractive', 'score': 0.6680101901292801, 
    'context': ' were, "That\'s one small step for [a] man, one giant leap for mankind." Aldrin joined him on the surface almost 20 minutes later. Altogether, they spe', 
    'offsets_in_document': [{'start': 240, 'end': 246}], 
    'offsets_in_context': [{'start': 72, 'end': 78}], 
    'document_id': 'ae1c366b1eaf5fc9d32a8d81f76bd795', 
    'meta': {
        'context': 'The first step was witnessed by at least one-fifth of the population of Earth, or about 723 million people. His first words when he stepped off the LM\'s landing footpad were, "That\'s one small step for [a] man, one giant leap for mankind." Aldrin joined him on the surface almost 20 minutes later. Altogether, they spent just under two and one-quarter hours outside their craft. The next day, they performed the first launch from another celestial body, and rendezvoused back with Columbia.', 'title': 'Space_Race'
        }
    }>
]
```


# Hugging Face Inference Endpoints
Source: https://docs.pinecone.io/integrations/hugging-face-inference-endpoints

Generate embeddings with Hugging Face Inference Endpoints and index them in Pinecone for semantic search, RAG, and transformer model deployment.

Hugging Face Inference Endpoints offers a secure production solution to easily deploy any Hugging Face Transformers, Sentence-Transformers and Diffusion models from the Hub on dedicated and autoscaling infrastructure managed by Hugging Face.

Coupled with Pinecone, you can use Hugging Face to generate and index high-quality vector embeddings with ease.

<PrimarySecondaryCTA />

## Setup guide

Hugging Face Inference Endpoints allows access to straightforward model inference. Coupled with Pinecone we can generate and index high-quality vector embeddings with ease.

Let's get started by initializing an Inference Endpoint for generating vector embeddings.

### Create an endpoint

We start by heading over to the [Hugging Face Inference Endpoints homepage](https://ui.endpoints.huggingface.co/endpoints) and signing up for an account if needed. After, we should find ourselves on this page:

<img alt="endpoints 0" />

We click on **Create new endpoint**, choose a model repository (eg name of the model), endpoint name (this can be anything), and select a cloud environment. Before moving on it is *very important* that we set the **Task** to **Sentence Embeddings** (found within the *Advanced configuration* settings).

<img alt="endpoints 1" />

<img alt="endpoints 2" />

Other important options include the *Instance Type*, by default this uses CPU which is cheaper but also slower. For faster processing we need a GPU instance. And finally, we set our privacy setting near the end of the page.

After setting our options we can click **Create Endpoint** at the bottom of the page. This action should take use to the next page where we will see the current status of our endpoint.

<img alt="endpoints 3" />

Once the status has moved from **Building** to **Running** (this can take some time), we're ready to begin creating embeddings with it.

## Create embeddings

Each endpoint is given an **Endpoint URL**, it can be found on the endpoint **Overview** page. We need to assign this endpoint URL to the `endpoint_url` variable.

<img alt="endpoints 4" />

```Python Python theme={null}
endpoint = "<ENDPOINT_URL>"
```

We will also need the organization API token, we find this via the organization settings on Hugging Face (`https://huggingface.co/organizations/<ORG_NAME>/settings/profile`). This is assigned to the `api_org` variable.

<img alt="endpoints 5" />

```Python Python theme={null}
api_org = "<API_ORG_TOKEN>"
```

Now we're ready to create embeddings via Inference Endpoints. Let's start with a toy example.

```Python Python theme={null}
import requests

# add the api org token to the headers
headers = {
    'Authorization': f'Bearer {api_org}'
}
# we add sentences to embed like so
json_data = {"inputs": ["a happy dog", "a sad dog"]}
# make the request
res = requests.post(
    endpoint,
    headers=headers,
    json=json_data
)
```

We should see a `200` response.

```Python Python theme={null}
res
```

```
<Response [200]>
```

Inside the response we should find two embeddings...

```Python Python theme={null}
len(res.json()['embeddings'])
```

```
2
```

We can also see the dimensionality of our embeddings like so:

```Python Python theme={null}
dim = len(res.json()['embeddings'][0])
dim
```

```
768
```

We will need more than two items to search through, so let's download a larger dataset. For this we will use Hugging Face datasets.

```Python Python theme={null}
from datasets import load_dataset

snli = load_dataset("snli", split='train')
snli
```

```
Downloading: 100%|██████████| 1.93k/1.93k [00:00<00:00, 992kB/s]
Downloading: 100%|██████████| 1.26M/1.26M [00:00<00:00, 31.2MB/s]
Downloading: 100%|██████████| 65.9M/65.9M [00:01<00:00, 57.9MB/s]
Downloading: 100%|██████████| 1.26M/1.26M [00:00<00:00, 43.6MB/s]

Dataset({
    features: ['premise', 'hypothesis', 'label'],
    num_rows: 550152
})
```

SNLI contains 550K sentence pairs, many of these include duplicate items so we will take just one set of these (the *hypothesis*) and deduplicate them.

```Python theme={null}
passages = list(set(snli['hypothesis']))
len(passages)
```

```
480042
```

We will drop to 50K sentences so that the example is quick to run, if you have time, feel free to keep the full 480K.

```Python Python theme={null}
passages = passages[:50_000]
```

## Create a Pinecone index

With our endpoint and dataset ready, all that we're missing is a vector database. For this, we need to initialize our connection to Pinecone, this requires a [free API key](https://app.pinecone.io/).

```Python Python theme={null}
import pinecone

# initialize connection to pinecone (get API key at app.pinecone.io)
pinecone.init(api_key="YOUR_API_KEY", environment="YOUR_ENVIRONMENT")

```

Now we create a new index called `'hf-endpoints'`, the name isn't important *but* the `dimension` must align to our endpoint model output dimensionality (we found this in `dim` above) and the model metric (typically `cosine` is okay, but not for all models).

```Python Python theme={null}
index_name = 'hf-endpoints'

# check if the hf-endpoints index exists
if index_name not in pinecone.list_indexes():
    # create the index if it does not exist
    pinecone.create_index(
        index_name,
        dimension=dim,
        metric="cosine"
    )

# connect to hf-endpoints index we created
index = pinecone.Index(index_name)
```

## Create and index embeddings

Now we have all of our components ready; endpoints, dataset, and Pinecone. Let's go ahead and create our dataset embeddings and index them within Pinecone.

```Python Python theme={null}
from tqdm.auto import tqdm

# we will use batches of 64
batch_size = 64

for i in tqdm(range(0, len(passages), batch_size)):
    # find end of batch
    i_end = min(i+batch_size, len(passages))
    # extract batch
    batch = passages[i:i_end]
    # generate embeddings for batch via endpoints
    res = requests.post(
        endpoint,
        headers=headers,
        json={"inputs": batch}
    )
    emb = res.json()['embeddings']
    # get metadata (just the original text)
    meta = [{'text': text} for text in batch]
    # create IDs
    ids = [str(x) for x in range(i, i_end)]
    # add all to upsert list
    to_upsert = list(zip(ids, emb, meta))
    # upsert/insert these records to pinecone
    _ = index.upsert(vectors=to_upsert)

# check that we have all vectors in index
index.describe_index_stats()
```

```
100%|██████████| 782/782 [11:02<00:00,  1.18it/s]

{'dimension': 768,
 'index_fullness': 0.1,
 'namespaces': {'': {'vector_count': 50000}},
 'total_vector_count': 50000}
```

With everything indexed we can begin querying. We will take a few examples from the *premise* column of the dataset.

```Python Python theme={null}
query = snli['premise'][0]
print(f"Query: {query}")
# encode with HF endpoints
res = requests.post(endpoint, headers=headers, json={"inputs": query})
xq = res.json()['embeddings']
# query and return top 5
xc = index.query(xq, top_k=5, include_metadata=True)
# iterate through results and print text
print("Answers:")
for match in xc['matches']:
    print(match['metadata']['text'])
```

```
Query: A person on a horse jumps over a broken down airplane.
Answers:
The horse jumps over a toy airplane.
a lady rides a horse over a plane shaped obstacle
A person getting onto a horse.
person rides horse
A woman riding a horse jumps over a bar.
```

These look good, let's try a couple more examples.

```Python Python theme={null}
query = snli['premise'][100]
print(f"Query: {query}")
# encode with HF endpoints
res = requests.post(endpoint, headers=headers, json={"inputs": query})
xq = res.json()['embeddings']
# query and return top 5
xc = index.query(xq, top_k=5, include_metadata=True)
# iterate through results and print text
print("Answers:")
for match in xc['matches']:
    print(match['metadata']['text'])
```

```
Query: A woman is walking across the street eating a banana, while a man is following with his briefcase.
Answers:
A woman eats a banana and walks across a street, and there is a man trailing behind her.
A woman eats a banana split.
A woman is carrying two small watermelons and a purse while walking down the street.
The woman walked across the street.
A woman walking on the street with a monkey on her back.
```

And one more...

```Python Python theme={null}
query = snli['premise'][200]
print(f"Query: {query}")
# encode with HF endpoints
res = requests.post(endpoint, headers=headers, json={"inputs": query})
xq = res.json()['embeddings']
# query and return top 5
xc = index.query(xq, top_k=5, include_metadata=True)
# iterate through results and print text
print("Answers:")
for match in xc['matches']:
    print(match['metadata']['text'])
```

```
Query: People on bicycles waiting at an intersection.
Answers:
A pair of people on bikes are waiting at a stoplight.
Bike riders wait to cross the street.
people on bicycles
Group of bike riders stopped in the street.
There are bicycles outside.
```

All of these results look excellent. If you are not planning on running your endpoint and vector DB beyond this tutorial, you can shut down both.

## Clean up

Shut down the endpoint by navigating to the Inference Endpoints **Overview** page and selecting **Delete endpoint**. Delete the Pinecone index with:

```Python Python theme={null}
pinecone.delete_index(index_name)
```

<Note>Once the index is deleted, you cannot use it again.</Note>


# Instill AI
Source: https://docs.pinecone.io/integrations/instill

Wire Pinecone into Instill AI no-code pipelines to upsert, query, and power RAG agents, chatbots, and knowledge bases with vector similarity.

Instill AI specializes in developing cutting-edge solutions for data, models, and pipeline orchestration. Their flagship source-available product, Instill Core, is a no-code/low-code platform designed to facilitate the development, deployment, and management of AI workflows. By simplifying the integration of various AI models and data sources, they enable businesses to harness the power of AI without requiring extensive technical expertise. Their solutions cater to a wide range of applications, from predictive analytics and autonomous AI agents to enterprise private knowledge bases, AI assistants, and beyond.

The Pinecone integration with Instill allows developers to incorporate its API for vector upsert and query tasks into AI pipelines. Developers configure their Pinecone component within Instill Core by providing the necessary API key and base URL. They can then perform tasks such as querying vector similarities to retrieve the most relevant results, complete with metadata and similarity scores, or upserting new vector data to keep their datasets up-to-date. This integration enables the addition of knowledge to LLMs via Retrieval Augmented Generation (RAG), significantly enhancing the capabilities of autonomous agents, chatbots, question-answering systems, and multi-agent systems.

<PrimarySecondaryCTA />


# Jina AI
Source: https://docs.pinecone.io/integrations/jina

Use Jina AI long-context embeddings with Pinecone for multilingual semantic search, RAG chatbots, and domain-specific retrieval up to 8K tokens.

Jina Embeddings leverage powerful models to generate high-quality text embeddings that can process inputs up to 8,000 tokens. Jina Embeddings are designed to be highly versatile, catering to both domain-specific use cases, such as e-commerce, and language-specific needs, including Chinese and German. By providing robust models and the expertise to fine-tune them for specific requirements, Jina AI empowers developers to enhance their search functionalities, improve natural language understanding, and drive more insightful data analysis.

By integrating Pinecone with Jina, you can add knowledge to LLMs via retrieval augmented generation (RAG), greatly enhancing LLM ability for autonomous agents, chatbots, question-answering, and multi-agent systems.

<PrimarySecondaryCTA />


# LangChain
Source: https://docs.pinecone.io/integrations/langchain

Build LangChain RAG apps, agents, and chatbots on Pinecone: manage embeddings, vector stores, retrievers, and chains for LLM-powered search.

LangChain provides modules for managing and optimizing the use of large language models (LLMs) in applications. Its core philosophy is to facilitate data-aware applications where the language model interacts with other data sources and its environment. This framework consists of several parts that simplify the entire application lifecycle:

* Write your applications in LangChain/LangChain.js. Get started quickly by using Templates for reference.
* Use LangSmith to inspect, test, and monitor your chains to constantly improve and deploy with confidence.
* Turn any chain into an API with LangServe.

By integrating Pinecone with LangChain, you can add knowledge to LLMs via retrieval augmented generation (RAG), greatly enhancing LLM ability for autonomous agents, chatbots, question-answering, and multi-agent systems.

<PrimarySecondaryCTA />

## Setup guide

This guide shows you how to integrate Pinecone, a high-performance vector database, with [LangChain](https://www.langchain.com/), a framework for building applications powered by large language models (LLMs).

Pinecone enables developers to build scalable, real-time recommendation and search systems based on vector similarity search. LangChain, on the other hand, provides modules for managing and optimizing the use of language models in applications. Its core philosophy is to facilitate data-aware applications where the language model interacts with other data sources and its environment.

By integrating Pinecone with LangChain, you can add knowledge to LLMs via [Retrieval Augmented Generation (RAG)](https://www.pinecone.io/learn/series/rag/), greatly enhancing LLM ability for autonomous agents, chatbots, question-answering, and multi-agent systems.

<Note>
  This guide demonstrates only one way out of many that you can use LangChain and Pinecone together. For additional examples, see:

  * [LangChain AI Handbook](https://www.pinecone.io/learn/series/langchain/)
  * [Retrieval Augmentation for LLMs](https://github.com/pinecone-io/examples/blob/master/learn/generation/langchain/handbook/05-langchain-retrieval-augmentation.ipynb)
  * [Retrieval Augmented Conversational Agent](https://github.com/pinecone-io/examples/blob/master/learn/generation/langchain/handbook/08-langchain-retrieval-agent.ipynb)
</Note>

## Key concepts

The `PineconeVectorStore` class provided by LangChain can be used to interact with Pinecone indexes. It's important to remember that you must have an existing Pinecone index before you can create a `PineconeVectorStore` object.

### Initializing a vector store

To initialize a `PineconeVectorStore` object, you must provide the name of the Pinecone index and an `Embeddings` object initialized through LangChain. There are two general approaches to initializing a `PineconeVectorStore` object:

1. Initialize without adding records:

```Python Python theme={null}
    import os
    from langchain_pinecone import PineconeVectorStore
    from langchain_openai import OpenAIEmbeddings

    os.environ['OPENAI_API_KEY'] = '<YOUR_OPENAI_API_KEY>'
    os.environ['PINECONE_API_KEY'] = '<YOUR_PINECONE_API_KEY>'

    index_name = "<YOUR_PINECONE_INDEX_NAME>"
    embeddings = OpenAIEmbeddings()

    vectorstore = PineconeVectorStore(index_name=index_name, embedding=embeddings)
```

You can also use the `from_existing_index` method of LangChain's `PineconeVectorStore` class to initialize a vector store.

2. Initialize while adding records:

The `from_documents` and `from_texts` methods of LangChain's `PineconeVectorStore` class add records to a Pinecone index and return a `PineconeVectorStore` object.

The `from_documents` method accepts a list of LangChain's `Document` class objects, which can be created using LangChain's `CharacterTextSplitter` class. The `from_texts` method accepts a list of strings. Similarly to above, you must provide the name of an existing Pinecone index and an `Embeddings` object.

Both of these methods handle the embedding of the provided text data and the creation of records in your Pinecone index.

```Python Python theme={null}
    import os
    from langchain_pinecone import PineconeVectorStore
    from langchain_openai import OpenAIEmbeddings
    from langchain_community.document_loaders import TextLoader
    from langchain_text_splitters import CharacterTextSplitter

    os.environ['OPENAI_API_KEY'] = '<YOUR_OPENAI_API_KEY>'
    os.environ['PINECONE_API_KEY'] = '<YOUR_PINECONE_API_KEY>'

    index_name = "<YOUR_PINECONE_INDEX_NAME>"
    embeddings = OpenAIEmbeddings()

    # path to an example text file
    loader = TextLoader("../../modules/state_of_the_union.txt")
    documents = loader.load()
    text_splitter = CharacterTextSplitter(chunk_size=1000, chunk_overlap=0)
    docs = text_splitter.split_documents(documents)

    vectorstore_from_docs = PineconeVectorStore.from_documents(
        docs,
        index_name=index_name,
        embedding=embeddings
    )

    texts = ["Tonight, I call on the Senate to: Pass the Freedom to Vote Act.", "ne of the most serious constitutional responsibilities a President has is nominating someone to serve on the United States Supreme Court.", "One of our nation’s top legal minds, who will continue Justice Breyer’s legacy of excellence."]

    vectorstore_from_texts = PineconeVectorStore.from_texts(
        texts,
        index_name=index_name,
        embedding=embeddings
    )
```

### Add more records

Once you have initialized a `PineconeVectorStore` object, you can add more records to the underlying Pinecone index (and thus also the linked LangChain object) using either the `add_documents` or `add_texts` methods.

Like their counterparts that also initialize a `PineconeVectorStore` object, both of these methods also handle the embedding of the provided text data and the creation of records in your Pinecone index.

```Python Python theme={null}
    # path to an example text file
    loader = TextLoader("../../modules/inaugural_address.txt")
    documents = loader.load()
    text_splitter = CharacterTextSplitter(chunk_size=1000, chunk_overlap=0)
    docs = text_splitter.split_documents(documents)

    vectorstore = PineconeVectorStore(index_name=index_name, embedding=embeddings)

    vectorstore.add_documents(docs)
```

```Python Python theme={null}
    vectorstore = PineconeVectorStore(index_name=index_name, embedding=embeddings)

    vectorstore.add_texts(["More text to embed and add to the index!"])
```

### Perform a similarity search

A `similarity_search` on a `PineconeVectorStore` object returns a list of LangChain `Document` objects most similar to the query provided. While the `similarity_search` uses a Pinecone query to find the most similar results, this method includes additional steps and returns results of a different type.

The `similarity_search` method accepts raw text and automatically embeds it using the `Embedding` object provided when you initialized the `PineconeVectorStore`. You can also provide a `k` value to determine the number of LangChain `Document` objects to return. The default value is `k=4`.

```Python Python theme={null}
    query = "Who is Ketanji Brown Jackson?"
    vectorstore.similarity_search(query)
    
    # Response:
    # [
    #    Document(page_content='Ketanji Onyika Brown Jackson is an American lawyer and jurist who is an associate justice of the Supreme Court of the United...', metadata={'chunk': 0.0, 'source': 'https://en.wikipedia.org/wiki/Ketanji_Brown_Jackson', 'title': 'Ketanji Brown Jackson', 'wiki-id': '6573'}),  
    #    Document(page_content='Jackson was nominated to the Supreme Court by President Joe Biden on February 25, 2022, and confirmed by the U.S. Senate...', metadata={'chunk': 1.0, 'source': 'https://en.wikipedia.org/wiki/Ketanji_Brown_Jackson', 'title': 'Ketanji Brown Jackson', 'wiki-id': '6573'}),  
    #    Document(page_content='Jackson grew up in Miami and attended Miami Palmetto Senior High School. She distinguished herself as a champion debater...', metadata={'chunk': 3.0, 'source': 'https://en.wikipedia.org/wiki/Ketanji_Brown_Jackson', 'title': 'Ketanji Brown Jackson', 'wiki-id': '6573'}),
    #    Document(page_content='After high school, Jackson matriculated at Harvard University to study government, having applied despite her guidance...', metadata={'chunk': 5.0, 'source': 'https://en.wikipedia.org/wiki/Ketanji_Brown_Jackson', 'title': 'Ketanji Brown Jackson', 'wiki-id': '6573'})
    # ]   
```

You can also optionally apply a metadata filter to your similarity search. The filtering query language is the same as for Pinecone queries, as detailed in [Filtering with metadata](https://docs.pinecone.io/guides/index-data/indexing-overview#metadata).

```Python Python theme={null}
    query = "Tell me more about Ketanji Brown Jackson."
    vectorstore.similarity_search(query, filter={'source': 'https://en.wikipedia.org/wiki/Ketanji_Brown_Jackson'})
```

### Namespaces

Several methods of the `PineconeVectorStore` class support using [namespaces](/guides/index-data/indexing-overview#namespaces). You can also initialize your `PineconeVectorStore` object with a namespace to restrict all further operations to that space.

```Python Python theme={null}
    index_name = "<YOUR_PINECONE_INDEX_NAME>"
    embeddings = OpenAIEmbeddings()

    vectorstore = PineconeVectorStore(index_name=index_name, embedding=embeddings, namespace="example-namespace")
```

If you initialize your `PineconeVectorStore` object without a namespace, you can specify the target namespace within the operation.

```Python Python theme={null}
    # path to an example text file
    loader = TextLoader("../../modules/congressional_address.txt")
    documents = loader.load()
    text_splitter = CharacterTextSplitter(chunk_size=1000, chunk_overlap=0)
    docs = text_splitter.split_documents(documents)

    vectorstore_from_docs = PineconeVectorStore.from_documents(
        docs,
        index_name=index_name,
        embedding=embeddings,
        namespace="example-namespace"
    )

    vectorstore_from_texts = PineconeVectorStore.from_texts(
        texts,
        index_name=index_name,
        embedding=embeddings,
        namespace="example-namespace"
    )

    vectorstore_from_docs.add_documents(docs, namespace="example-namespace")

    vectorstore_from_texts.add_texts(["More text!"], namespace="example-namespace")
```

```Python Python theme={null}
    query = "Who is Ketanji Brown Jackson?"
    vectorstore.similarity_search(query, namespace="example-namespace")
```

## Tutorial

### 1. Set up your environment

Before you begin, install some necessary libraries and set environment variables for your Pinecone and OpenAI API keys:

```Shell theme={null}
pip install -qU \
  "pinecone[grpc]"==5.1.0 \
  pinecone-datasets==0.7.0 \
  langchain-pinecone==0.1.2 \
  langchain-openai==0.1.23 \
  langchain==0.2.15
```

```bash theme={null}
# Set environment variables for API keys
export PINECONE_API_KEY="{{YOUR_API_KEY}}"  # Get from app.pinecone.io
export OPENAI_API_KEY="your-openai-api-key"  # Get from platform.openai.com/api-keys
```

```Python Python theme={null}
import os
pinecone_api_key = os.environ.get('PINECONE_API_KEY')
openai_api_key = os.environ.get('OPENAI_API_KEY')
```

### 2. Build the knowledge base

1. Load a [sample Pinecone dataset](/guides/data/use-public-pinecone-datasets) into memory:

   ```Python Python theme={null}
   import pinecone_datasets  
   dataset = pinecone_datasets.load_dataset('wikipedia-simple-text-embedding-ada-002-100K')  
   len(dataset)  

   # Response:
   # 100000
   ```

2. Reduce the dataset and format it for upserting into Pinecone:

   ```Python Python theme={null}
   # we will use rows of the dataset up to index 30_000
   dataset.documents.drop(dataset.documents.index[30_000:], inplace=True)
   # we drop sparse_values as they are not needed for this example  
   dataset.documents.drop(['metadata'], axis=1, inplace=True)  
   dataset.documents.rename(columns={'blob': 'metadata'}, inplace=True)  
   ```

### 3. Index the data in Pinecone

1. Initialize your client connection to Pinecone and create an index. This step uses the Pinecone API key you set as an environment variable [earlier](#1-set-up-your-environment).

   ```Python Python theme={null}
   from pinecone.grpc import PineconeGRPC as Pinecone
   from pinecone import ServerlessSpec, PodSpec  
   import time  
   # configure client  
   pc = Pinecone(api_key=pinecone_api_key)  
   spec = ServerlessSpec(cloud='aws', region='us-east-1')  
   # check for and delete index if already exists  
   index_name = 'langchain-retrieval-augmentation-fast'  
   if pc.has_index(index_name):  
       pc.delete_index(name=index_name)  
   # create a new index  
   pc.create_index(  
       index_name,  
       dimension=1536,  # dimensionality of text-embedding-ada-002  
       metric='dotproduct',  
       spec=spec  
   )  
   ```

2. Target the index and check its current stats:

   ```Python Python theme={null}
   index = pc.Index(index_name)  
   index.describe_index_stats()  

   # Response:
   # {'dimension': 1536,  
   # 'index_fullness': 0.0,  
   # 'namespaces': {},  
   # 'total_vector_count': 0}  
   ```

   You'll see that the index has a `total_vector_count` of `0`, as you haven't added any vectors yet.

3. Now upsert the data to Pinecone:

   ```Python Python theme={null}
   for batch in dataset.iter_documents(batch_size=100):  
       index.upsert(batch)  
   ```

4. Once the data is indexed, check the index stats once again:

   ```Python Python theme={null}
   index.describe_index_stats()  

   # Response:
   # {'dimension': 1536,  
   # 'index_fullness': 0.0,  
   # 'namespaces': {},  
   # 'total_vector_count': 70000} 
   ```

### 4. Initialize a LangChain vector store

Now that you've built your Pinecone index, you need to initialize a LangChain vector store using the index. This step uses the OpenAI API key you set as an environment variable [earlier](#1-set-up-your-environment). Note that OpenAI is a paid service and so running the remainder of this tutorial may incur some small cost.

1. Initialize a LangChain embedding object:

   ```Python Python theme={null}
   from langchain_openai import OpenAIEmbeddings  
   # get openai api key from platform.openai.com  
   model_name = 'text-embedding-ada-002'  
   embeddings = OpenAIEmbeddings(  
       model=model_name,  
       openai_api_key=openai_api_key  
   )  
   ```

2. Initialize the LangChain vector store:

   The `text_field` parameter sets the name of the metadata field that stores the raw text when you upsert records using a LangChain operation such as `vectorstore.from_documents` or `vectorstore.add_texts`.
   This metadata field is used as the `page_content` in the `Document` objects retrieved from query-like LangChain operations such as `vectorstore.similarity_search`.
   If you do not specify a value for `text_field`, it will default to `"text"`.

   ```Python Python theme={null}
   from langchain_pinecone import PineconeVectorStore  
   text_field = "text"  
   vectorstore = PineconeVectorStore(  
       index, embeddings, text_field  
   )  
   ```

3. Now you can query the vector store directly using `vectorstore.similarity_search`:

   ```Python Python theme={null}
   query = "who was Benito Mussolini?"  
   vectorstore.similarity_search(  
       query,  # our search query  
       k=3  # return 3 most relevant docs  
   )  

   # Response:
   # [Document(page_content='Benito Amilcare Andrea Mussolini KSMOM GCTE (29 July 1883 – 28 April 1945) was an Italian politician and journalist...', metadata={'chunk': 0.0, 'source': 'https://simple.wikipedia.org/wiki/Benito%20Mussolini', 'title': 'Benito Mussolini', 'wiki-id': '6754'}),  
   # Document(page_content='Fascism as practiced by Mussolini\nMussolini\'s form of Fascism, "Italian Fascism"- unlike Nazism, the racist ideology...', metadata={'chunk': 1.0, 'source': 'https://simple.wikipedia.org/wiki/Benito%20Mussolini', 'title': 'Benito Mussolini', 'wiki-id': '6754'}),  
   # Document(page_content='Veneto was made part of Italy in 1866 after a war with Austria. Italian soldiers won Latium in 1870. That was when...', metadata={'chunk': 5.0, 'source': 'https://simple.wikipedia.org/wiki/Italy', 'title': 'Italy', 'wiki-id': '363'})]
   ```

All of these sample results are good and relevant. But what else can you do with this? There are many tasks, one of the most interesting (and well supported by LangChain) is called "Generative Question-Answering" or GQA.

### 5. Use Pinecone and LangChain for RAG

In RAG, you take the query as a question that is to be answered by a LLM, but the LLM must answer the question based on the information it is seeing from the vectorstore.

1. To do this, initialize a `RetrievalQA` object like so:

   ```Python Python theme={null}
   from langchain_openai import ChatOpenAI  
   from langchain.chains import RetrievalQA  
   # completion llm  
   llm = ChatOpenAI(  
       openai_api_key=OPENAI_API_KEY,  
       model_name='gpt-3.5-turbo',  
       temperature=0.0  
   )  
   qa = RetrievalQA.from_chain_type(  
       llm=llm,  
       chain_type="stuff",  
       retriever=vectorstore.as_retriever()  
   )  
   qa.invoke(query)  

   # Response:
   # Benito Mussolini was an Italian politician and journalist who served as the Prime Minister of Italy from 1922 until 1943. He was the leader of the National Fascist Party and played a significant role in the rise of fascism in Italy...
   ```

2. You can also include the sources of information that the LLM is using to answer your question using a slightly different version of `RetrievalQA` called `RetrievalQAWithSourcesChain`:

   ```Python Python theme={null}
   from langchain.chains import RetrievalQAWithSourcesChain  
   qa_with_sources = RetrievalQAWithSourcesChain.from_chain_type(  
       llm=llm,  
       chain_type="stuff",  
       retriever=vectorstore.as_retriever()  
   )  
   qa_with_sources.invoke(query)

   # Response:
   # {'question': 'who was Benito Mussolini?',  
   # 'answer': "Benito Mussolini was an Italian politician and journalist who served as the Prime Minister of Italy from 1922 until 1943. He was the leader of the National Fascist Party and played a significant role in the rise of fascism in Italy...",  
   # 'sources': 'https://simple.wikipedia.org/wiki/Benito%20Mussolini'}  
   ```

### 6. Clean up

When you no longer need the index, use the `delete_index` operation to delete it:

```Python Python theme={null}
pc.delete_index(name=index_name)
```

## Related articles

* [LangChain AI Handbook](https://www.pinecone.io/learn/series/langchain/)


# Langtrace
Source: https://docs.pinecone.io/integrations/langtrace

Trace Pinecone API calls with Langtrace's OpenTelemetry SDK to debug RAG pipelines, monitor vector DB latency, and ship LLM observability.

Scale3 Labs recently launched Langtrace AI, an open-source monitoring and evaluation platform for LLM-powered applications. Langtrace is built based on Open Telemetry(OTEL) standards and supports native tracing for the most popular LLM vendors, VectorDBs, and frameworks(like Langchain and LlamaIndex).

Langtrace AI supports tracing Pinecone natively, which means the Langtrace SDK can generate OTEL standard traces with automatic instrumentation in just 2 lines of code. These traces can be ingested by an observability tool that supports OTEL, such as Datadog, Grafana/Prometheus, SigNoz, Sentry, etc. Langtrace also has a visualization client that is optimized for visualizing the traces generated in an LLM stack.

By having a Pinecone integration, Pinecone users can get access to rich and high cardinal tracing for the Pinecone API calls using Langtrace, which they can ingest into their observability tool of choice. This helps customers gain insights into the DB calls and help with debugging and troubleshooting applications in case of incidents.

<PrimarySecondaryCTA />


# LlamaIndex
Source: https://docs.pinecone.io/integrations/llamaindex

Build LlamaIndex RAG pipelines on Pinecone: ingest documents, structure private data, and run semantic search and question-answering over LLMs.

LlamaIndex is a framework for connecting data sources to LLMs, with its chief use case being the end-to-end development of retrieval augmented generation (RAG) applications. LlamaIndex provides the essential abstractions to more easily ingest, structure, and access private or domain-specific data in order to inject these safely and reliably into LLMs for more accurate text generation. It’s available in Python and Typescript.

Seamlessly integrate Pinecone vector database with LlamaIndex to build semantic search and RAG applications.

<PrimarySecondaryCTA />

## Setup guide

[View source](https://github.com/pinecone-io/examples/blob/master/learn/generation/llama-index/using-llamaindex-with-pinecone.ipynb)

[Open in Colab](https://colab.research.google.com/github/pinecone-io/examples/blob/master/learn/generation/llama-index/using-llamaindex-with-pinecone.ipynb)

[LlamaIndex](https://www.llamaindex.ai/) is a framework for connecting data sources to LLMs, with its chief use case being the end-to-end development of [RAG applications](https://www.pinecone.io/learn/retrieval-augmented-generation/). Compared to other similar frameworks, LlamaIndex offers a wide variety of tools for pre- and post-processing your data.

This guide shows you how to use LlamaIndex and Pinecone to both perform traditional semantic search and build a RAG pipeline. Specifically, you will:

* Load, transform, and vectorize sample data with LlamaIndex
* Index and store the vectorized data in Pinecone
* Search the data in Pinecone and use the results to augment an LLM call
* Evaluate the answer you get back from the LLM

<Note>
  This guide demonstrates only one way out of many that you can use LlamaIndex as part of a RAG pipeline. See LlamaIndex's section on [Advanced RAG](https://docs.llamaindex.ai/en/stable/optimizing/advanced%5Fretrieval/advanced%5Fretrieval.html) to learn more about what's possible.
</Note>

### Set up your environment

Before you begin, install some necessary libraries and set environment variables for your Pinecone and OpenAI API keys:

```Shell Shell theme={null}
# Install libraries
pip install -qU \
    "pinecone[grpc]"==5.1.0 \
    llama-index==0.11.4 \
    llama-index-vector-stores-pinecone==0.2.1 \
    llama-index-readers-file==0.2.0 \
    arxiv==2.1.3 \
    setuptools  # (Optional)
```

```bash Shell theme={null}
# Set environment variables for API keys
export PINECONE_API_KEY="your-pinecone-api-key"  # Get from app.pinecone.io
export OPENAI_API_KEY="your-openai-api-key"  # Get from platform.openai.com/api-keys
```

Also note that all code on this page is run on Python 3.11.

### Load the data

In this guide, you will use the [canonical HNSW paper](https://arxiv.org/pdf/1603.09320.pdf) by Yuri Malkov (PDF) as your sample dataset. Your first step is to download the PDF from arXiv.org and load it into a LlamaIndex loader called [PDF Loader](https://llamahub.ai/l/file-pdf?from=all). This Loader is available (along with many more) on the [LlamaHub](https://llamahub.ai/), which is a directory of data loaders.

```Python Python theme={null}
import arxiv
from pathlib import Path
from llama_index.readers.file import PDFReader

# Download paper to local file system (LFS)
# `id_list` contains 1 item that matches our PDF's arXiv ID
paper = next(arxiv.Client().results(arxiv.Search(id_list=["1603.09320"])))
paper.download_pdf(filename="hnsw.pdf")

# Instantiate `PDFReader` from LlamaHub
loader = PDFReader()

# Load HNSW PDF from LFS
documents = loader.load_data(file=Path('./hnsw.pdf'))

# Preview one of our documents
documents[0]
# Response:
# Document(id_='e25106d2-bde5-41f0-83fa-5cbfa8234bef', embedding=None, metadata={'page_label': '1', 'file_name': 'hnsw.pdf'}, excluded_embed_metadata_keys=[], excluded_llm_metadata_keys=[], relationships={}, text="IEEE TRANSACTIONS ON  JOURNAL NAME,  MANUS CRIPT ID  1 \n Efficient and robust approximate nearest \nneighbor search using Hierarchical Navigable \nSmall World graphs  \nYu. A. Malkov,  D. A. Yashunin  \nAbstract  — We present a new approach for the approximate K -nearest neighbor search based on navigable small world \ngraphs with controllable hierarchy (Hierarchical NSW , HNSW ) and tree alg o-\nrithms", start_char_idx=None, end_char_idx=None, text_template='{metadata_str}\n\n{content}', metadata_template='{key}: {value}', metadata_seperator='\n')
```

You can see above that each `Document` has a ton of useful information, but depending on which Loader you choose, you may have to clean your data. In this case, you need to remove things like remaining `\n` characters and broken, hyphenated words (e.g., `alg o-\nrithms` → `algorithms`).

```Python Python theme={null}
# Clean up our Documents' content
import re

def clean_up_text(content: str) -> str:
    """
    Remove unwanted characters and patterns in text input.

    :param content: Text input.
    
    :return: Cleaned version of original text input.
    """

    # Fix hyphenated words broken by newline
    content = re.sub(r'(\w+)-\n(\w+)', r'\1\2', content)

    # Remove specific unwanted patterns and characters
    unwanted_patterns = [
        "\\n", "  —", "——————————", "—————————", "—————",
        r'\\u[\dA-Fa-f]{4}', r'\uf075', r'\uf0b7'
    ]
    for pattern in unwanted_patterns:
        content = re.sub(pattern, "", content)

    # Fix improperly spaced hyphenated words and normalize whitespace
    content = re.sub(r'(\w)\s*-\s*(\w)', r'\1-\2', content)
    content = re.sub(r'\s+', ' ', content)

    return content

# Call function
cleaned_docs = []
for d in documents: 
    cleaned_text = clean_up_text(d.text)
    d.text = cleaned_text
    cleaned_docs.append(d)

# Inspect output
cleaned_docs[0].get_content()
# Response:
# "IEEE TRANSACTIONS ON JOURNAL NAME, MANUS CRIPT ID 1 Efficient and robust approximate nearest neighbor search using Hierarchical Navigable Small World graphs Yu. A. Malkov, D. A. Yashunin Abstract We present a new approach for the approximate K-nearest neighbor search based on navigable small world graphs with controllable hierarchy (Hierarchical NSW , HNSW ) and tree algorithms."

# Great!
```

The value-add of using a file loader from LlamaHub is that your PDF is already broken down into LlamaIndex [Documents](https://docs.llamaindex.ai/en/stable/module%5Fguides/loading/documents%5Fand%5Fnodes/root.html#documents-nodes). Along with each Document object comes a [customizable](https://docs.llamaindex.ai/en/stable/module%5Fguides/loading/documents%5Fand%5Fnodes/usage%5Fdocuments.html#metadata) metadata dictionary and a hash ID, among other useful artifacts.

### Transform the data

#### Metadata

Now, if you look at one of your cleaned Document objects, you'll see that the default values in your metadata dictionary are not particularly useful.

```Python Python theme={null}
cleaned_docs[0].metadata
# Response:
# {'page_label': '1', 'file_name': 'hnsw.pdf'}
```

To add some metadata that would be more helpful, let's add author name and the paper's title. Note that whatever metadata you add to the metadata dictionary will apply to all [Nodes](https://docs.llamaindex.ai/en/stable/module%5Fguides/loading/documents%5Fand%5Fnodes/root.html#nodes), so you want to keep your additions high-level.

<Note>
  LlamaIndex also provides [advanced customizations](https://docs.llamaindex.ai/en/stable/module%5Fguides/loading/documents%5Fand%5Fnodes/usage%5Fdocuments.html#advanced-metadata-customization) for what metadata the LLM can see vs the embedding, etc.
</Note>

```Python Python theme={null}
# Iterate through `documents` and add our new key:value pairs
metadata_additions = {"authors": ["Yu. A. Malkov", "D. A. Yashunin"],
  "title": "Efficient and robust approximate nearest neighbor search using Hierarchical Navigable Small World graphs"}

 # Update dict in place
[cd.metadata.update(metadata_additions) for cd in cleaned_docs]
 
# Let\'s confirm everything worked:
cleaned_docs[0].metadata
# Response:
# {'page_label': '1',
#      'file_name': 'hnsw.pdf',
#      'authors': ['Yu. A. Malkov', 'D. A. Yashunin'],
#      'title': 'Efficient and robust approximate nearest neighbor search using Hierarchical Navigable Small World graphs'}

# Great!
```

#### Ingestion pipeline

The easiest way to turn your data into indexable vectors and put those into Pinecone is to make what's called an [Ingestion Pipeline](https://docs.llamaindex.ai/en/stable/module%5Fguides/loading/ingestion%5Fpipeline/root.html). Ingestion Pipelines are how you will build a pipeline that will take your list of Documents, parse them into Nodes (or “[chunks](https://www.pinecone.io/learn/chunking-strategies/)” in non-LlamaIndex contexts), vectorize each Node's content, and upsert them into Pinecone.

In the following pipeline, you'll use one of LlamaIndex's newer parsers: the [SemanticSplitterNodeParser](https://docs.llamaindex.ai/en/stable/module%5Fguides/loading/node%5Fparsers/modules.html#semanticsplitternodeparser), which uses OpenAI's [ada-002 embedding model](https://github.com/run-llama/llama%5Findex/blob/47b34d1fdfde2ded134a373b620c3e7a694e8380/llama%5Findex/embeddings/openai.py#L216) to split Documents into semantically coherent Nodes.

This step uses the OpenAI API key you set as an environment variable [earlier](#set-up-your-environment).

```Python Python theme={null}
import os

from llama_index.node_parser import SemanticSplitterNodeParser
from llama_index.embeddings import OpenAIEmbedding
from llama_index.ingestion import IngestionPipeline

# This will be the model we use both for Node parsing and for vectorization
embed_model = OpenAIEmbedding(api_key=openai_api_key)

# Define the initial pipeline
pipeline = IngestionPipeline(
    transformations=[
        SemanticSplitterNodeParser(
            buffer_size=1,
            breakpoint_percentile_threshold=95, 
            embed_model=embed_model,
            ),
        embed_model,
        ],
    )
```

Hold off on running this pipeline; you will modify it below.

### Upsert the data

Above, you defined an Ingestion Pipeline. There's one thing missing, though: a vector database into which you can upsert your transformed data.

LlamaIndex lets you declare a [VectorStore](https://docs.llamaindex.ai/en/stable/examples/vector%5Fstores/pinecone%5Fmetadata%5Ffilter.html) and add that right into the pipeline for super easy ingestion. Let's do that with Pinecone below.

This step uses the Pinecone API key you set as an environment variable [earlier](#set-up-your-environment).

```Python Python theme={null}
from pinecone.grpc import PineconeGRPC
from pinecone import ServerlessSpec

from llama_index.vector_stores.pinecone import PineconeVectorStore

# Initialize connection to Pinecone
pc = PineconeGRPC(api_key=pinecone_api_key)
index_name = "llama-integration-example"

# Create your index (can skip this step if your index already exists)
pc.create_index(
    index_name,
    dimension=1536,
    spec=ServerlessSpec(cloud="aws", region="us-east-1"),
)

# Initialize your index 
pinecone_index = pc.Index(index_name)

# Initialize VectorStore
vector_store = PineconeVectorStore(pinecone_index=pinecone_index)
```

With your PineconeVectorStore now initialized, you can pop that into your `pipeline` and run it.

```Python Python theme={null}
# Our pipeline with the addition of our PineconeVectorStore
pipeline = IngestionPipeline(
    transformations=[
        SemanticSplitterNodeParser(
            buffer_size=1,
            breakpoint_percentile_threshold=95, 
            embed_model=embed_model,
            ),
        embed_model,
        ],
        vector_store=vector_store  # Our new addition
    )

# Now we run our pipeline!
pipeline.run(documents=cleaned_docs)
```

Now ensure your index is up and running with some Pinecone-native methods like `.describe_index_stats()`:

```Python Python theme={null}
pinecone_index.describe_index_stats()

# Response:
# {'dimension': 1536,
# 'index_fullness': 0.0,
# 'namespaces': {'': {'vector_count': 46}},
# 'total_vector_count': 46}
```

Awesome, your index now has vectors in it. Since you have 46 vectors, you can infer that your `SemanticSplitterNodeParser` split your list of Documents into 46 Nodes.

#### Query the data

To fetch search results from Pinecone itself, you need to make a [VectorStoreIndex](https://docs.llamaindex.ai/en/stable/module%5Fguides/indexing/vector%5Fstore%5Findex.html) object and a [VectorIndexRetriever](https://github.com/run-llama/llama%5Findex/blob/main/llama%5Findex/indices/vector%5Fstore/retrievers/retriever.py#L21) object. You can then pass natural language queries to your Pinecone index and receive results.

```Python Python theme={null}
from llama_index.core import VectorStoreIndex
from llama_index.core.retrievers import VectorIndexRetriever

# Instantiate VectorStoreIndex object from your vector_store object
vector_index = VectorStoreIndex.from_vector_store(vector_store=vector_store)

# Grab 5 search results
retriever = VectorIndexRetriever(index=vector_index, similarity_top_k=5)

# Query vector DB
answer = retriever.retrieve('How does logarithmic complexity affect graph construction?')

# Inspect results
print([i.get_content() for i in answer])

# Response:
# ['some relevant search result 1', 'some relevant search result 1'...]
```

These search results can now be plugged into any downstream task you want.

One of the most common ways to use vector database search results is as additional context to augment a query sent to an LLM. This workflow is what's commonly referred to as a [RAG application](https://www.pinecone.io/learn/retrieval-augmented-generation/).

### Build a RAG app with the data

Building a RAG app with LlamaIndex is very simple.

In theory, you could create a simple [Query Engine](https://docs.llamaindex.ai/en/stable/module%5Fguides/deploying/query%5Fengine/usage%5Fpattern.html#usage-pattern) out of your `vector_index` object by calling `vector_index.as_query_engine().query(‘some query')`, but then you wouldn't be able to specify the number of Pinecone search results you'd like to use as context.

To control how many search results your RAG app uses from your Pinecone index, you will instead create your Query Engine using the [RetrieverQueryEngine](https://github.com/run-llama/llama%5Findex/blob/main/llama%5Findex/query%5Fengine/retriever%5Fquery%5Fengine.py#L21) class. This class allows you to pass in the `retriever` created above, which you configured to retrieve the top 5 search results.

```Python Python theme={null}
from llama_index.core.query_engine import RetrieverQueryEngine

# Pass in your retriever from above, which is configured to return the top 5 results
query_engine = RetrieverQueryEngine(retriever=retriever)

# Now you query:
llm_query = query_engine.query('How does logarithmic complexity affect graph construction?')

llm_query.response
# Response:
# 'Logarithmic complexity in graph construction affects the construction process by organizing the graph into different layers based on their length scale. This separation of links into layers allows for efficient and scalable routing in the graph. The construction algorithm starts from the top layer, which contains the longest links, and greedily traverses through the elements until a local minimum is reached. Then, the search switches to the lower layer with shorter links, and the process repeats. By keeping the maximum number of connections per element constant in all layers, the routing complexity in the graph scales logarithmically. This logarithmic complexity is achieved by assigning an integer level to each element, determining the maximum layer it belongs to. The construction algorithm incrementally builds a proximity graph for each layer, consisting of "short" links that approximate the Delaunay graph. Overall, logarithmic complexity in graph construction enables efficient and robust approximate nearest neighbor search.'
```

You can even inspect the context (Nodes) that informed your LLM's answer using the `.source_nodes` attribute. Let's inspect the first Node:

```Python Python theme={null}
llm_response_source_nodes = [i.get_content() for i in llm_query.source_nodes]

llm_response_source_nodes
# Response:
# ["AUTHOR ET AL.: TITL E 7 be auto-configured by using sample data. The construction process can be easily and efficiently parallelized with only few synchronization points (as demonstrated in Fig. 9) and no measurable effect on index quality. Construction speed/index q uality tradeoff is co ntrolled via the efConstruction parameter. The tradeoff between the search time and the index construction time is presented in Fig. 10 for a 10M SIFT dataset and shows that a reasonable quality index can be constructed for efConstruct ion=100 on a 4X 2.4 GHz 10-core X..."]
```

### Evaluate the data

Now that you've made a RAG app and queried your LLM, you need to evaluate its response.

With LlamaIndex, there are [many ways](https://docs.llamaindex.ai/en/module%5Fguides/evaluating/usage%5Fpattern.html#) to evaluate the results your RAG app generates. A great way to get started with evaluation is to confirm (or deny) that your LLM's responses are relevant, given the context retrieved from your vector database. To do this, you can use LlamaIndex's [RelevancyEvaluator](https://docs.llamaindex.ai/en/stable/examples/evaluation/relevancy%5Feval.html#relevancy-evaluator) class.

The great thing about this type of evaluation is that there is no need for [ground truth data](https://dtunkelang.medium.com/evaluating-search-using-human-judgement-fbb2eeba37d9) (i.e., labeled datasets to compare answers with).

```Python Python theme={null}
from llama_index.core.evaluation import RelevancyEvaluator

# (Need to avoid peripheral asyncio issues)
import nest_asyncio
nest_asyncio.apply()

# Define evaluator
evaluator = RelevancyEvaluator()

# Issue query
llm_response = query_engine.query(
    "How does logarithmic complexity affect graph construction?"
)

# Grab context used in answer query & make it pretty
llm_response_source_nodes = [i.get_content() for i in llm_response.source_nodes]

# # Take your previous question and pass in the response youwe got above
eval_result = evaluator.evaluate_response(query="How does logarithmic complexity affect graph construction?", response=llm_response)

# Print response
print(f'\nGiven the {len(llm_response_source_nodes)} chunks of content (below), is your '
      f'LLM\'s response relevant? {eval_result.passing}\n'
      f'\n ----Contexts----- \n'
      f'\n{llm_response_source_nodes}')
# Response:
# "Given the 5 chunks of content (below), is your LLM's response relevant? True
         
#  ----Contexts----- 
         
# ['AUTHOR ET AL.: TITL E 7 be auto-configured by using sample data. The construction process can be easily and efficiently parallelized with only few synchronization points (as demonstrated in Fig...']"
```

You can see that there are various attributes you can inspect on your evaluator's result in order to ascertain what's going on behind the scenes. To get a quick binary True/False signal as to whether your LLM is producing relevant results given your context, inspect the `.passing` attribute.

Let's see what happens when we send a totally out of scope query through your RAG app. Issue a random query you know your RAG app won't be able to answer, given what's in your index:

```Python Python theme={null}
query = "Why did the chicken cross the road?"
response = query_engine.query(query)

print(response.response)
# Response:
# "I'm sorry, but I cannot answer that question based on the given context information."

# Evaluate
eval_result = evaluator.evaluate_response(query=query, response=response)

print(str(eval_result.passing))
# Response:
# False  # Our LLM is not taking our context into account, as expected :)
```

As expected, when you send an out-of-scope question through your RAG pipeline, your evaluator says the LLM's answer is not relevant to the retrieved context.

### Summary

As you have seen, LlamaIndex is a powerful framework to use when building semantic search and RAG applications – and we have only gotten to the tip of the iceberg! [Explore more](https://docs.llamaindex.ai/en/index.html) on your own and [let us know how it goes](https://community.pinecone.io/).


# Matillion
Source: https://docs.pinecone.io/integrations/matillion

Use Matillion Data Productivity Cloud to chunk, embed, and upsert data into Pinecone with low-code AI pipelines for RAG, ETL, and GenAI apps.

[Matillion Data Productivity Cloud](https://www.matillion.com/) is a unified platform that helps your team move faster with one central place to build and manage graphical, low-code data pipelines. It allows data teams to use structured, semi-structured, and unstructured data in analytics; build AI pipelines for new use cases; and be more productive.

Matillion Data Productivity Cloud and Pinecone can be used together for retrieval augmented generation (RAG) use cases, helping to contextualize business insights without code.

Matillion supports 150+ pre-built data source connectors, as well as the ability to build custom connectors to any REST API source system, making it easy to chunk unstructured datasets, create embeddings, and upsert to Pinecone.
Matillion's graphical AI Prompt Components integrate with large language models (LLM) running in OpenAI, Amazon Bedrock, Azure OpenAI, and Snowpark Container Services. They enable no-code lookup of external knowledge stored in Pinecone, enabling data engineers to enrich GenAI answers with contextualized and proprietary data.

<PrimarySecondaryCTA />

## Additional resources

* Video: [Use RAG with a Pinecone Vector database on the Data Productivity Cloud](https://www.youtube.com/watch?v=BsH7WlJdoFs)
* Video: [How to upsert to your Pinecone Vector database](https://www.youtube.com/watch?v=l9qt-EzLkgY)
* [Unlock the power of AI in Data Engineering](https://www.matillion.com/blog/matillion-new-ai-capabilities-for-data-engineering)


# Microsoft Marketplace
Source: https://docs.pinecone.io/integrations/microsoft-marketplace

Buy and manage Pinecone through Microsoft Marketplace with pay-as-you-go billing, centralized SaaS procurement, and simplified Azure licensing.

Access Pinecone through our Microsoft Marketplace listing. Microsoft Marketplace allows you to manage Pinecone and other third-party software from a centralized location, and simplifies software licensing and procurement with flexible pricing options and multiple deployment methods.

You can set up pay-as-you-go billing for a Pinecone organization through the Microsoft Marketplace

<PrimarySecondaryCTA />


# n8n
Source: https://docs.pinecone.io/integrations/n8n

Automate Pinecone vector store and Assistant workflows in n8n: build RAG pipelines, semantic search, and no-code AI automations with 400+ apps.

n8n is a workflow automation platform that combines AI capabilities with business process automation, giving technical teams the flexibility of code with the speed of no-code. Integrate Pinecone Vector Database or Pinecone Assistant nodes directly into your automation pipelines to build powerful AI workflows with vector search and retrieval.

Released under a fair-code license, n8n can be self-hosted and is supported by a vibrant community of developers and builders. Use the visual builder for quick wins and add custom Javascript or Python where you need more control.

## Two ways to use Pinecone in n8n

**[Pinecone Vector Store integration on n8n](https://n8n.io/integrations/pinecone-vector-store/)** — Use this for full control over RAG pipelines. Provides direct access to Pinecone's vector database so you can choose embedding models, customize chunking, and control search (semantic, lexical, or hybrid). Ideal for wiring up custom nodes for each step and tuning everything to specific use cases. See the [Pinecone Vector Store integration on n8n](https://n8n.io/integrations/pinecone-vector-store/) for node docs, supported modes (insert, retrieve, update), and workflow templates.

**[Pinecone Assistant integration on n8n](https://n8n.io/integrations/pinecone-assistant/)** — Use this for managed RAG with minimal setup. Upload files (PDF, DOCX, TXT, JSON, Markdown), connect any data source, and get production-ready knowledge retrieval. One node handles chunking, embedding, vector search, query planning, and reranking. Ideal for building AI workflows that need trusted, grounded context without configuring pipelines. See the [Pinecone Assistant integration on n8n](https://n8n.io/integrations/pinecone-assistant/) for installation and workflow templates.

The quickstart below uses the **Pinecone Assistant** node.

<PrimarySecondaryCTA />

## Getting started (Pinecone Assistant)

Follow our [complete Assistant quickstart guide](/guides/assistant/quickstart/n8n-quickstart) to:

* Install the Pinecone Assistant node in n8n
* Get your API keys
* Create your first assistant
* Import a ready-to-use workflow template
* Start chatting with your documents

Or use the [n8n skill](/guides/get-started/ai-coding-tools) to build n8n workflows in agentic IDEs aned CLIs like Claude Code, Cursor, and more.


# New Relic
Source: https://docs.pinecone.io/integrations/new-relic

Monitor Pinecone with New Relic's Prometheus quickstart: dashboards, alerts, and AI observability for vector database latency and RAG performance.

New Relic is an all-in-one observability platform and provides the industry’s first APM solution for AI-powered applications. New Relic is pioneering AI observability with AIM to provide engineers unprecedented visibility and insights across the AI application stack, making it easier to troubleshoot and optimize their AI applications for performance, quality, cost, and responsible use of AI.

Implement monitoring and integrate your Pinecone application with New Relic for performance analysis and insights. The New Relic for Pinecone (Prometheus) quickstart contains one dashboard. These interactive visualizations let you easily explore your data, understand context, and resolve problems faster. It also includes three alerts to detect changes in key performance metrics. Integrate these alerts with your favorite tools (like Slack, PagerDuty, etc.) and New Relic will let you know when something needs your attention.

<PrimarySecondaryCTA />


# Nexla
Source: https://docs.pinecone.io/integrations/nexla

Use Nexla no-code data pipelines to ingest from SharePoint, OneDrive, and 500+ sources into Pinecone for enterprise RAG and vector search apps.

Nexla is a Data + AI Integration Platform that makes it easy for users to build data pipelines in a no-code/low-code manner.

The Pinecone integration with Nexla makes it easy for enterprise users to ingest data from systems like Sharepoint, OneDrive, Cloud Storage, Data Warehouses, and 500+ other connectors that Nexla supports natively.

<PrimarySecondaryCTA />


# Nuclia
Source: https://docs.pinecone.io/integrations/nuclia

Power Nuclia RAG-as-a-Service with Pinecone: index documents, customize retrieval and chunking strategies, and deploy LLM knowledge boxes at scale.

[Nuclia](https://nuclia.com/) RAG-as-a-Service automatically indexes files and documents from both internal and external sources, powering diverse company use cases with large language models (LLMs). This comprehensive indexing capability ensures that organizations can leverage unstructured data effectively, transforming it into actionable insights. With Nuclia's modular Retrieval-Augmented Generation (RAG) system, you can deploy solutions tailored to various operational needs across different deployment options, enhancing flexibility and efficiency.

The modular RAG system from Nuclia is designed to fit specific use cases, allowing you to customize your RAG pipeline to meet your unique requirements. Whether it's defining your own retrieval and chunking strategies or choosing from various embedding models, Nuclia's RAG-as-a-Service makes it easy to bring your tailored solutions into production. This customization not only improves the value of your products but also helps you stay competitive by automating tasks and making your data smarter with LLMs, saving hundreds of hours in the process.

When you create a knowledge box at Nuclia, choose to store the index in Pinecone. This is especially useful for large datasets where full text search is not key on the retrieval phase.

<PrimarySecondaryCTA />


# OctoAI
Source: https://docs.pinecone.io/integrations/octoai

Combine OctoAI's GTE Large embeddings and open-source LLMs with Pinecone and Canopy for cost-effective RAG, semantic search, and generative AI apps.

Harness value from the latest AI innovations by delievering efficient, reliable, and customizable AI systems for your apps. Run your models or checkpoints on OctoAI's cost-effective API endpoints, or run OctoAI's optimized GenAI stack in your environment.

Choose from the best models that OctoAI has to offer, including GTE Large embedding model, the best foundational open source LLMs such as Mixtral-8x7B from Mistral AI, Llama2 from Meta, and highly capable model fine tunes like Nous Hermes 2 Pro Mistral from Nous Research.

As a fully open source solution, Pinecone Canopy and OctoAI is one of the fastest ways and more affordable ways to get started on your RAG journey. Canopy uses Pinecone vector database for storage and retrieval, which is free to use for up to 100k vectors (that's about 30k pages of text).

<PrimarySecondaryCTA />


# OpenAI
Source: https://docs.pinecone.io/integrations/openai

Pair OpenAI embeddings and completion models with Pinecone for semantic search, long-term memory, RAG, and context-aware LLM question-answering.

OpenAI's large language models (LLMs) enhance semantic search or “long-term memory” for LLMs. This combo utilizes LLMs' embedding and completion (or generation) endpoints alongside Pinecone's vector search capabilities for nuanced information retrieval.

By integrating OpenAI's LLMs with Pinecone, you can combine deep learning capabilities for embedding generation with efficient vector storage and retrieval. This approach surpasses traditional keyword-based search, offering contextually-aware, precise results.

<PrimarySecondaryCTA />

## Setup guide

[View source](https://github.com/pinecone-io/examples/blob/master/integrations/openai/)

[Open in Colab](https://colab.research.google.com/github/pinecone-io/examples/blob/master/integrations/openai/semantic_search_openai.ipynb)

This guide covers the integration of OpenAI's Large Language Models (LLMs) with Pinecone (referred to as the **OP stack**), enhancing semantic search or 'long-term memory' for LLMs. This combo utilizes LLMs' embedding and completion (or generation) endpoints alongside Pinecone's vector search capabilities for nuanced information retrieval.

LLMs like OpenAI's `text-embedding-ada-002` generate vector embeddings, i.e., numerical representations of text semantics. These embeddings facilitate semantic-based rather than literal textual matches. Additionally, LLMs like `gpt-4` or `gpt-3.5-turbo` can predict text completions based on information provided from these contexts.

Pinecone is a vector database designed for storing and querying high-dimensional vectors. It provides fast, efficient semantic search over these vector embeddings.

By integrating OpenAI's LLMs with Pinecone, we combine deep learning capabilities for embedding generation with efficient vector storage and retrieval. This approach surpasses traditional keyword-based search, offering contextually-aware, precise results.

There are many ways of integrating these two tools and we have several guides focusing on specific use-cases. If you already know what you'd like to do you can jump to these specific materials:

* [ChatGPT Plugins Walkthrough](https://youtu.be/hpePPqKxNq8)
* [Ask Lex ChatGPT Plugin](https://github.com/pinecone-io/examples/tree/master/learn/generation/openai/chatgpt/plugins/ask-lex)
* [Generative Question-Answering](https://github.com/pinecone-io/examples/blob/master/docs/gen-qa-openai.ipynb)
* [Retrieval Augmentation using LangChain](https://github.com/pinecone-io/examples/blob/master/learn/generation/langchain/handbook/05-langchain-retrieval-augmentation.ipynb)

### Introduction to Embeddings

At the core of the OP stack we have embeddings which are supported via the [OpenAI Embedding API](https://beta.openai.com/docs/guides/embeddings). We index those embeddings in the [Pinecone vector database](https://www.pinecone.io) for fast and scalable retrieval augmentation of our LLMs or other information retrieval use-cases.

*This example demonstrates the core OP stack. It is the simplest workflow and is present in each of the other workflows, but is not the only way to use the stack. Please see the links above for more advanced usage.*

The OP stack is built for semantic search, question-answering, threat-detection, and other applications that rely on language models and a large corpus of text data.

The basic workflow looks like this:

* Embed and index
  * Use the OpenAI Embedding API to generate vector embeddings of your documents (or any text data).
  * Upload those vector embeddings into Pinecone, which can store and index millions/billions of these vector embeddings, and search through them at ultra-low latencies.
* Search
  * Pass your query text or document through the OpenAI Embedding API again.
  * Take the resulting vector embedding and send it as a [query](/guides/search/search-overview) to Pinecone.
  * Get back semantically similar documents, even if they don't share any keywords with the query.

<img alt="Basic workflow of OpenAI and Pinecone" />

Let's get started...

### Environment Setup

We start by installing the OpenAI and Pinecone clients, we will also need HuggingFace *Datasets* for downloading the TREC dataset that we will use in this guide.

```Bash Bash theme={null}
!pip install -qU \
    pinecone[grpc]==7.3.0 \
    openai==1.93.0 \
    datasets==3.6.0
```

#### Creating Embeddings

To create embeddings we must first initialize our connection to OpenAI Embeddings, we sign up for an API key at [OpenAI](https://beta.openai.com/signup).

```Python Python theme={null}
from openai import OpenAI

client = OpenAI(
    api_key="OPENAI_API_KEY"
)  # get API key from platform.openai.com
```

We can now create embeddings with the OpenAI v3 small embedding model like so:

```Python Python theme={null}
MODEL = "text-embedding-3-small"

res = client.embeddings.create(
    input=[
        "Sample document text goes here",
        "there will be several phrases in each batch"
    ], model=MODEL
)
```

In `res` we should find a JSON-like object containing two 1536-dimensional embeddings, these are the vector representations of the two inputs provided above. To access the embeddings directly we can write:

```Python Python theme={null}
# we can extract embeddings to a list
embeds = [record.embedding for record in res.data]
len(embeds)
```

We will use this logic when creating our embeddings for the **T**ext **RE**trieval **C**onference (TREC) question classification dataset later.

#### Initializing a Pinecone Index

Next, we initialize an index to store the vector embeddings. For this we need a Pinecone API key, [sign up for one here](https://app.pinecone.io).

```Python Python theme={null}
import time
from pinecone.grpc import PineconeGRPC as Pinecone
from pinecone import ServerlessSpec

pc = Pinecone(api_key="...")

spec = ServerlessSpec(cloud="aws", region="us-east-1")

index_name = 'semantic-search-openai'

# check if index already exists (it shouldn't if this is your first run)
if index_name not in pc.list_indexes().names():
    # if does not exist, create index
    pc.create_index(
        index_name,
        dimension=len(embeds[0]),  # dimensionality of text-embed-3-small
        metric='dotproduct',
        spec=spec
    )

# connect to index
index = pc.Index(index_name)
time.sleep(1)
# view index stats
index.describe_index_stats()
```

#### Populating the Index

With both OpenAI and Pinecone connections initialized, we can move onto populating the index. For this, we need the TREC dataset.

```Python Python theme={null}
from datasets import load_dataset

# load the first 1K rows of the TREC dataset
trec = load_dataset('trec', split='train[:1000]')
```

Then we create a vector embedding for each question using OpenAI (as demonstrated earlier), and `upsert` the ID, vector embedding, and original text for each phrase to Pinecone.

<Warning>
  High-cardinality metadata values (like the unique text values we use here)\
  can reduce the number of vectors that fit on a single pod. See\
  [Known limitations](/reference/api/known-limitations) for more.
</Warning>

```Python Python theme={null}
from tqdm.auto import tqdm

count = 0  # we'll use the count to create unique IDs
batch_size = 32  # process everything in batches of 32
for i in tqdm(range(0, len(trec['text']), batch_size)):
    # set end position of batch
    i_end = min(i+batch_size, len(trec['text']))
    # get batch of lines and IDs
    lines_batch = trec['text'][i: i+batch_size]
    ids_batch = [str(n) for n in range(i, i_end)]
    # create embeddings
    res = client.embeddings.create(input=lines_batch, model=MODEL)
    embeds = [record.embedding for record in res.data]
    # prep metadata and upsert batch
    meta = [{'text': line} for line in lines_batch]
    to_upsert = zip(ids_batch, embeds, meta)
    # upsert to Pinecone
    index.upsert(vectors=list(to_upsert))
```

#### Querying

With our data indexed, we're now ready to move onto performing searches. This follows a similar process to indexing. We start with a text `query`, that we would like to use to find similar sentences. As before we encode this with OpenAI's text similarity Babbage model to create a *query vector* `xq`. We then use `xq` to query the Pinecone index.

```Python Python theme={null}
query = "What caused the 1929 Great Depression?"

xq = client.embeddings.create(input=query, model=MODEL).data[0].embedding
```

Now we query.

```Python Python theme={null}
res = index.query(vector=xq, top_k=5, include_metadata=True)
```

The response from Pinecone includes our original text in the `metadata` field, let's print out the `top_k` most similar questions and their respective similarity scores.

```Python Python theme={null}
for match in res['matches']:
    print(f"{match['score']:.2f}: {match['metadata']['text']}")
```

```[Out]: theme={null}
0.75: Why did the world enter a global depression in 1929 ?
0.60: When was `` the Great Depression '' ?
0.37: What crop failure caused the Irish Famine ?
0.32: What were popular songs and types of songs in the 1920s ?
0.32: When did World War I start ?
```

Looks good, let's make it harder and replace *"depression"* with the incorrect term *"recession"*.

```Python Python theme={null}
query = "What was the cause of the major recession in the early 20th century?"

# create the query embedding
xq = client.embeddings.create(input=query, model=MODEL).data[0].embedding

# query, returning the top 5 most similar results
res = index.query(vector=xq, top_k=5, include_metadata=True)

for match in res['matches']:
    print(f"{match['score']:.2f}: {match['metadata']['text']}")
```

```[Out]: theme={null}
0.63: Why did the world enter a global depression in 1929 ?
0.55: When was `` the Great Depression '' ?
0.34: What were popular songs and types of songs in the 1920s ?
0.33: What crop failure caused the Irish Famine ?
0.29: What is considered the costliest disaster the insurance industry has ever faced ?
```

Let's perform one final search using the definition of depression rather than the word or related words.

```Python Python theme={null}
query = "Why was there a long-term economic downturn in the early 20th century?"

# create the query embedding
xq = client.embeddings.create(input=query, model=MODEL).data[0].embedding

# query, returning the top 5 most similar results
res = index.query(vector=xq, top_k=5, include_metadata=True)

for match in res['matches']:
    print(f"{match['score']:.2f}: {match['metadata']['text']}")
```

```[Out]: theme={null}
0.62: Why did the world enter a global depression in 1929 ?
0.54: When was `` the Great Depression '' ?
0.34: What were popular songs and types of songs in the 1920s ?
0.33: What crop failure caused the Irish Famine ?
0.32: What do economists do ?
```

It's clear from this example that the semantic search pipeline is clearly able to identify the meaning between each of our queries. Using these embeddings with Pinecone allows us to return the most semantically similar questions from the already indexed TREC dataset.

Once we're finished with the index we delete it to save resources.

```Python Python theme={null}
pc.delete_index(name=index_name)
```

## Related articles

* [Generative Question-Answering with Long-Term Memory](https://www.pinecone.io/learn/openai-gen-qa)
* [OpenAI's Text Embeddings v3](https://www.pinecone.io/learn/openai-embeddings-v3/)


# Pulumi
Source: https://docs.pinecone.io/integrations/pulumi

Provision Pinecone indexes and collections as code with Pulumi in Python, TypeScript, Go, or C# for infrastructure-as-code vector database DevOps.

Pulumi is an infrastructure as code platform that allows you to use familiar programming languages and tools to build, deploy, and manage cloud infrastructure. Pulumi is free, open source, and optionally pairs with the Pulumi Cloud to make managing infrastructure secure, reliable, and hassle-free.

This Pulumi Pinecone Provider enables you to manage your Pinecone collections and indexes using any language of Pulumi Infrastructure as Code.

<PrimarySecondaryCTA />


# Redpanda
Source: https://docs.pinecone.io/integrations/redpanda

Stream events into Pinecone with Redpanda Connect's declarative YAML pipelines for real-time vector ingestion, at-least-once delivery, and RAG ETL.

Redpanda Connect is a declarative data streaming service that solves a wide range of data engineering problems with simple, chained, stateless processing steps. It implements transaction based resiliency with back pressure, so when connecting to at-least-once sources and sinks, it's able to guarantee at-least-once delivery without needing to persist messages during transit.

It's simple to deploy, comes with a wide range of connectors, and is totally data agnostic, making it easy to drop into your existing infrastructure. Redpanda Connect has functionality that overlaps with integration frameworks, log aggregators and ETL workflow engines, and can therefore be used to complement these traditional data engineering tools or act as a simpler alternative.

The Pinecone connector for Redpanda provides a production-ready integration from many existing data sources, all in a few lines of YAML.

<PrimarySecondaryCTA />


# Snowflake
Source: https://docs.pinecone.io/integrations/snowflake

Deploy Pinecone on Snowpark Container Services to run vector search and GenAI apps inside Snowflake without moving data out of your warehouse.

Deploy and run Pinecone with Snowpark Container Services. Snowpark Container Services is a fully managed container offering designed to facilitate the deployment, management, and scaling of containerized applications within the Snowflake ecosystem. This service enables users to run containerized workloads directly within Snowflake, ensuring that data does't need to be moved out of the Snowflake environment for processing. Unlike traditional container orchestration platforms like Docker or Kubernetes, Snowpark Container Services offers an OCI runtime execution environment specifically optimized for Snowflake. This integration allows for the seamless execution of OCI images, leveraging Snowflak's robust data platform.

<PrimarySecondaryCTA />

## Related articles

* [Snowpark Container Services: Securely Deploy and run Sophisticated Generative AI and full-stack apps in Snowflake](https://www.snowflake.com/blog/snowpark-container-services-deploy-genai-full-stack-apps/)


# StreamNative
Source: https://docs.pinecone.io/integrations/streamnative

Pipe Apache Pulsar topics to Pinecone via the StreamNative sink connector for real-time vector ingestion, event streaming, and Kafka-compatible RAG.

Founded by the original developers of Apache Pulsar and Apache BookKeeper, [StreamNative](https://streamnative.io) provides StreamNative Cloud, offering Apache Pulsar as a Service. The company also supports on-premise Pulsar deployments and related commercial support. StreamNative Cloud provides a scalable, resilient, and secure messaging and event streaming platform for enterprises. Additionally, StreamNative offers Kafka compatibility, enabling seamless integration with existing Kafka-based systems.

The Pinecone integration with StreamNative allows access to pinecone.io with a Pulsar topic. The sink connector takes in messages and writes them if they are in a proper format to a Pinecone index.

<PrimarySecondaryCTA />


# Terraform
Source: https://docs.pinecone.io/integrations/terraform

Manage Pinecone indexes, collections, API keys, and projects with the Terraform provider for repeatable infrastructure-as-code and DevOps workflows.

Terraform is an infrastructure as code tool that lets you create, update, and version infrastructure by defining resources in configuration files. This allows for a repeated workflow for provisioning and managing your infrastructure.

This page describes how to use the [Terraform Provider for Pinecone](https://registry.terraform.io/providers/pinecone-io/pinecone/latest/docs) to manage Pinecone indexes, collections, projects, API keys, service accounts, role bindings, invites, and users.

## Requirements

Ensure you have the following:

* [Terraform](https://developer.hashicorp.com/terraform) >= v1.4.6
* A [Pinecone API key](https://app.pinecone.io/organizations/-/keys) for managing indexes and collections
* A [Pinecone service account](https://app.pinecone.io/organizations/-/settings/access/service-accounts) for managing projects, API keys, service accounts, role bindings, invites, and users

<Note>
  [Go](https://go.dev/doc/install) >= v1.24 is required only if you build the provider from source. You don't need Go to install the provider from the Terraform Registry.
</Note>

## Install the provider

1. Configure the Pinecone provider in your Terraform configuration file:

   ```terraform theme={null}
   terraform {
     required_providers {
       pinecone = {
         source  = "pinecone-io/pinecone"
         version = "~> 4.0"
       }
     }
   }
   ```

````

1. Run `terraform init` to install the provider from the [Terraform Registry](https://registry.terraform.io/providers/pinecone-io/pinecone/latest). Alternatively, you can download the latest binary for your target platform from the [GitHub repository](https://github.com/pinecone-io/terraform-provider-pinecone/releases).

<Note>
Upgrading from v2 doesn't require configuration changes. No arguments were removed or renamed in v3 or v4, so existing configuration keeps working. Both releases only add resources, data sources, and index options. For the full list, see the [v3.0.0](https://github.com/pinecone-io/terraform-provider-pinecone/releases/tag/v3.0.0) and [v4.0.0](https://github.com/pinecone-io/terraform-provider-pinecone/releases/tag/v4.0.0) release notes.
</Note>

## Authenticate 

The provider uses two kinds of credentials, and each resource requires a specific one. The provider needs at least one of them and fails to configure if neither is set. If your configuration manages both indexes and organization-level resources, set both.

| Credential | Environment variables | Resources and data sources |
| :--- | :--- | :--- |
| [API key](/guides/projects/manage-api-keys) | `PINECONE_API_KEY` | `pinecone_index`, `pinecone_collection` |
| [Service account](/guides/organizations/manage-service-accounts) | `PINECONE_CLIENT_ID`, `PINECONE_CLIENT_SECRET` | `pinecone_project`, `pinecone_api_key`, `pinecone_service_account`, `pinecone_role_binding`, `pinecone_invite`, `pinecone_user` |

To authenticate:

1. Set environment variables for authentication:

    ```bash
    # For indexes and collections  
    export PINECONE_API_KEY="YOUR_API_KEY"

    # For projects, API keys, service accounts, role bindings, invites, and users
    export PINECONE_CLIENT_ID="YOUR_CLIENT_ID"
    export PINECONE_CLIENT_SECRET="YOUR_CLIENT_SECRET"
````

1. Append the following to your Terraform configuration file:

   ```terraform theme={null}
   provider "pinecone" {}
   ```

````

<Note>
You can also set the API key and service account credentials as [input variables](https://developer.hashicorp.com/terraform/language/values/variables).
</Note>

## Manage resources

The Terraform Provider for Pinecone provides the following resources:

| Resource | Description | Credential |
| :--- | :--- | :--- |
| [`pinecone_index`](#indexes) | Create, update, and delete indexes. | API key |
| [`pinecone_collection`](#collections) | Create and delete collections. | API key |
| [`pinecone_project`](#projects) | Create, update, and delete projects. | Service account |
| [`pinecone_api_key`](#api-keys) | Create, update, and delete API keys. | Service account |
| [`pinecone_service_account`](#service-accounts) | Create, update, and delete service accounts. | Service account |
| [`pinecone_role_binding`](#role-bindings) | Grant and revoke roles. | Service account |
| [`pinecone_invite`](#invites) | Send and revoke organization invitations. | Service account |
| [`pinecone_user`](#users) | Remove existing organization members. | Service account |

### Indexes

The `pinecone_index` resource lets you create, update, and delete [indexes](/guides/index-data/indexing-overview). 

```terraform
# Index for dense vectors
resource "pinecone_index" "example_index" {
  name        = "example-index"
  dimension   = 1536
  metric      = "cosine"
  vector_type = "dense"
  spec = {
    serverless = {
      cloud  = "aws"
      region = "us-west-2"
    }
  }
  deletion_protection = "disabled"
  tags = {
    environment = "development"
  }
}

# Index for dense vectors with integrated embedding
resource "pinecone_index" "example_index_integrated" {
  name = "example-index-integrated"
  spec = {
    serverless = {
      cloud  = "aws"
      region = "us-west-2"
    }
  }
  embed = {
    model = "llama-text-embed-v2"
    field_map = {
      text = "chunk_text"
    }
    read_parameters = {
      input_type = "query"
    }
    write_parameters = {
      input_type = "passage"
    }
  }
}
````

For an index with integrated embedding, `dimension` defaults to the model's dimension. The `model` can't be changed once set, but you can update `field_map`, `read_parameters`, and `write_parameters`. The read-only `embed.effective_read_parameters` and `embed.effective_write_parameters` attributes report the parameters the API applied, including server-side defaults you didn't set.

<Note>
  You can [update](/guides/manage-data/manage-indexes) only the deletion protection, tags, integrated inference embedding settings, and [read capacity](#read-capacity) of an index. Changing any other attribute — including `name`, `dimension`, `metric`, the cloud and region, or the [metadata schema](#metadata-schema) — replaces the index.
</Note>

#### BYOC indexes

To create a [BYOC index](/guides/production/bring-your-own-cloud), set `spec.byoc.environment` to the environment identifier Pinecone provides for your deployment:

```terraform theme={null}
resource "pinecone_index" "example_index_byoc" {
  name      = "example-index-byoc"
  dimension = 1536
  spec = {
    byoc = {
      environment = "YOUR_BYOC_ENVIRONMENT_ID"
    }
  }
}
```

#### Pod-based indexes

<Warning>
  Customers who sign up for a Standard or Enterprise plan on or after August 18, 2025 cannot create pod-based indexes. Instead, create [serverless indexes](/guides/index-data/create-an-index), and consider using [dedicated read nodes](/guides/index-data/dedicated-read-nodes) for large workloads (millions of records or more, and moderate or high query rates).
</Warning>

To create a [pod-based index](/guides/indexes/pods/understanding-pod-based-indexes), set `spec.pod`:

```terraform theme={null}
resource "pinecone_index" "example_index_pod" {
  name      = "example-index-pod"
  dimension = 1536
  spec = {
    pod = {
      environment = "us-west4-gcp"
      pod_type    = "s1.x1"
      replicas    = 1
      shards      = 1
      metadata_config = {
        indexed = ["genre"]
      }
    }
  }
}
```

<Warning>
  Changing `replicas`, `shards`, or `pod_type` replaces the index, which deletes the records it holds. To scale a pod-based index in place, use the [console or API](/guides/indexes/pods/manage-pod-based-indexes) instead.
</Warning>

#### Read capacity

Serverless and BYOC indexes support configurable read capacity through `read_capacity` inside the `serverless` or `byoc` spec. There are two modes: `on_demand`, which is the default, and `dedicated`, which provisions [dedicated read nodes](/guides/index-data/dedicated-read-nodes).

```terraform theme={null}
# On-demand read capacity, stated explicitly
resource "pinecone_index" "example_index_on_demand" {
  name      = "example-index-on-demand"
  dimension = 1536
  spec = {
    serverless = {
      cloud  = "aws"
      region = "us-east-1"
      read_capacity = {
        on_demand = {}
      }
    }
  }
}

# Dedicated read capacity
resource "pinecone_index" "example_index_dedicated" {
  name      = "example-index-dedicated"
  dimension = 1536
  spec = {
    serverless = {
      cloud  = "aws"
      region = "us-east-1"
      read_capacity = {
        dedicated = {
          node_type = "b1"
          replicas  = 1
          shards    = 1
        }
      }
    }
  }
}
```

Set `node_type` to `b1` or `t1`. The first time you switch an index to dedicated mode, `node_type`, `replicas`, and `shards` are all required.

#### Metadata schema

Serverless and BYOC indexes support a `schema` block that controls [metadata indexing](/guides/index-data/create-an-index#metadata-indexing). By default, all metadata is indexed. When `schema` is present, only the fields you list with `filterable = true` are indexed.

```terraform theme={null}
resource "pinecone_index" "example_index_schema" {
  name      = "example-index-schema"
  dimension = 1536
  spec = {
    serverless = {
      cloud  = "aws"
      region = "us-east-1"
      schema = {
        fields = {
          "category" = { filterable = true }
          "language" = { filterable = true }
        }
      }
    }
  }
}
```

<Warning>
  You can set `schema` only when you create an index. Changing it replaces the index, which deletes the records it holds.
</Warning>

#### Timeouts

Index creation and deletion both time out after 5 minutes by default. To override this, set a `timeouts` block:

```terraform theme={null}
resource "pinecone_index" "example_index_timeouts" {
  name      = "example-index-timeouts"
  dimension = 1536
  spec = {
    serverless = {
      cloud  = "aws"
      region = "us-east-1"
    }
  }

  timeouts {
    create = "10m"
    delete = "10m"
  }
}
```

### Collections

The `pinecone_collection` resource lets you create and delete [collections](/guides/indexes/pods/understanding-collections) for pod-based indexes. Set `source` to the name of the source index.

```terraform theme={null}
resource "pinecone_index" "example_index" {
  name      = "example-index"
  dimension = 10
  spec = {
    pod = {
      environment = "us-west4-gcp"
      pod_type    = "s1.x1"
    }
  }
}

resource "pinecone_collection" "example_collection" {
  name   = "example-collection"
  source = pinecone_index.example_index.name
}
```

Collections also accept a `timeouts` block, with the same 5-minute defaults as indexes.

### Projects

The `pinecone_project` resource lets you create, update, and delete [projects](/guides/projects/understanding-projects). Once `force_encryption_with_cmek` is enabled, it can't be disabled. `max_pods` defaults to `0`, which allows serverless indexes only.

<Warning>
  Customers who sign up for a Standard or Enterprise plan on or after August 18, 2025 cannot create pod-based indexes. Instead, create [serverless indexes](/guides/index-data/create-an-index), and consider using [dedicated read nodes](/guides/index-data/dedicated-read-nodes) for large workloads (millions of records or more, and moderate or high query rates).
</Warning>

Customers on those plans also can't set `max_pods` for a project.

```terraform theme={null}
# Basic project
resource "pinecone_project" "example_project" {
  name = "example-project"
}

# Project with CMEK encryption enabled
resource "pinecone_project" "example_project_encrypted" {
  name                       = "example-project-encrypted"
  force_encryption_with_cmek = true
}

# Project with custom max pods
resource "pinecone_project" "example_project_custom_pods" {
  name     = "example-project-custom-pods"
  max_pods = 10
}

output "project_organization_id" {
  description = "The organization the project belongs to"
  value       = pinecone_project.example_project.organization_id
}
```

### API keys

The `pinecone_api_key` resource lets you create, update, and delete [API keys](/guides/projects/manage-api-keys). Valid `roles` values are `ProjectEditor`, `ProjectViewer`, `ControlPlaneEditor`, `ControlPlaneViewer`, `DataPlaneEditor`, and `DataPlaneViewer`. `roles` defaults to `["ProjectEditor"]`.

<Note>
  You can update only the name and roles of an API key. `project_id` is required when you create a key.
</Note>

```terraform theme={null}
# API key with default roles (ProjectEditor)
resource "pinecone_api_key" "example_key" {
  name       = "example-key"
  project_id = "YOUR_PROJECT_ID"
}

# API key with custom roles
resource "pinecone_api_key" "example_key_custom_roles" {
  name       = "example-key-custom-roles"
  project_id = "YOUR_PROJECT_ID"
  roles      = ["ProjectViewer", "DataPlaneViewer"]
}

output "api_key_roles" {
  description = "The roles assigned to the API key"
  value       = pinecone_api_key.example_key.roles
}
```

<Warning>
  The generated secret is available as the read-only `key` attribute, which the API returns only once, at creation. Terraform stores it in plaintext in state. Marking it sensitive keeps it out of CLI output and logs, but does not encrypt it in state. Secure your state backend and never commit state to version control.
</Warning>

### Service accounts

The `pinecone_service_account` resource lets you create, update, and delete [service accounts](/guides/organizations/manage-service-accounts). A service account authenticates with an OAuth client ID and secret. Grant it roles with a [role binding](#role-bindings).

```terraform theme={null}
resource "pinecone_service_account" "example_service_account" {
  name = "example-service-account"
}

resource "pinecone_role_binding" "example_service_account_org_member" {
  principal_id   = pinecone_service_account.example_service_account.id
  principal_type = "service_account"
  resource_type  = "organization"
  role           = "OrgMember"
}

# Rotate the client secret by changing rotate_trigger to a new value
resource "pinecone_service_account" "example_service_account_rotatable" {
  name           = "example-service-account-rotatable"
  rotate_trigger = "2026-01-01"
}

output "example_service_account_client_secret" {
  value     = pinecone_service_account.example_service_account.client_secret
  sensitive = true
}
```

To rotate a client secret, change `rotate_trigger` from one non-empty value to another. Setting it for the first time, or clearing it, establishes a baseline without rotating, so an existing credential is never invalidated unintentionally.

<Warning>
  The `client_secret` attribute is returned only once, at creation or rotation, and Terraform stores it in plaintext in state. Marking it sensitive keeps it out of CLI output and logs, but does not encrypt it in state. Secure your state backend and never commit state to version control.
</Warning>

### Role bindings

The `pinecone_role_binding` resource lets you grant a role to a principal at organization or project scope. For details on the role model, see [Manage roles and access](/guides/production/manage-rbac).

* Set `principal_type` to `user`, `service_account`, or `api_key`, and `principal_id` to that principal's ID.
* Set `resource_type` to `organization` or `project`. For project scope, `resource_id` is required and must be the project ID. For organization scope, omit `resource_id`. The binding applies to the caller's organization.
* Organization-scoped `role` values are `OrgOwner`, `OrgManager`, `OrgBillingAdmin`, and `OrgMember`. Project-scoped values are `ProjectOwner`, `ProjectManager`, `ProjectMember`, `ProjectEditor`, `ProjectViewer`, `ControlPlaneEditor`, `ControlPlaneViewer`, `DataPlaneEditor`, and `DataPlaneViewer`.

```terraform theme={null}
# Organization-scoped role
resource "pinecone_role_binding" "example_org_member" {
  principal_id   = "YOUR_SERVICE_ACCOUNT_ID"
  principal_type = "service_account"
  resource_type  = "organization"
  role           = "OrgMember"
}

# Project-scoped role
resource "pinecone_role_binding" "example_project_editor" {
  principal_id   = "YOUR_USER_ID"
  principal_type = "user"
  resource_type  = "project"
  resource_id    = "YOUR_PROJECT_ID"
  role           = "ProjectEditor"
}
```

<Note>
  Role bindings are immutable. Changing any attribute revokes the existing binding and creates a new one.
</Note>

The `pinecone_role_binding` resource doesn't accept `principal_type = "invite"`. Pinecone moves an invite's bindings to the user principal when the invite is accepted, so Terraform can't manage them across that transition. To grant roles to someone who hasn't joined your organization yet, use [`pinecone_invite`](#invites), then manage their roles here with `principal_type = "user"` once they accept. The `pinecone_role_bindings` data source does accept `invite`, so you can still read what a pending invite granted.

### Invites

The `pinecone_invite` resource manages an [organization invitation](/guides/organizations/manage-organization-members), not the resulting membership. Creating it sends an invite to the given email with a set of initial roles. Deleting it revokes an invite that is still pending. The `role_bindings` list must include at least one organization-scoped role that grants membership.

```terraform theme={null}
# Invite a user as an organization member
resource "pinecone_invite" "example_member" {
  email = "teammate@example.com"

  role_bindings = [
    {
      resource_type = "organization"
      role          = "OrgMember"
    }
  ]
}

# Invite a user with both organization membership and a project-scoped role
resource "pinecone_invite" "example_project_editor" {
  email = "contractor@example.com"

  role_bindings = [
    {
      resource_type = "organization"
      role          = "OrgMember"
    },
    {
      resource_type = "project"
      role          = "ProjectEditor"
      resource_id   = "YOUR_PROJECT_ID"
    }
  ]
}
```

The read-only `status` attribute reports `pending`, `expired`, or `processed`. Invites expire 7 days after creation, and the provider doesn't expose a way to change that. Once an invite is accepted, its status is `processed` and Terraform stops acting on it. Destroying an accepted invite is a no-op.

<Warning>
  Invites are immutable, so changing `email` or `role_bindings` sends a new invite. Don't change either one after the invite is accepted — the replacement re-invites an address that already belongs to a member, and the operation fails. Manage an existing member's roles with [`pinecone_role_binding`](#role-bindings) instead.
</Warning>

<Note>
  Pinecone doesn't return the roles an invite granted, so `role_bindings` is applied only at creation. Terraform can't detect drift on it or recover it on import. To read the bindings, use the `pinecone_role_bindings` data source with `principal_type = "invite"`.
</Note>

### Users

The `pinecone_user` resource manages an existing [organization member](/guides/organizations/manage-organization-members). You can't create or update users through Terraform. They join your organization by accepting an [invite](#invites). Bring an existing user under management with [`terraform import`](#import-existing-resources). To change a user's roles, use a [role binding](#role-bindings).

<Warning>
  Destroying a `pinecone_user` resource removes that person from your organization. A `terraform destroy`, or removing the resource from your configuration, revokes a colleague's access to every project in the organization.
</Warning>

```terraform theme={null}
resource "pinecone_user" "example_user" {
  id = "YOUR_USER_ID"
}
```

The `id` attribute is immutable. To manage a different user, run `terraform state rm` on this resource and import the intended one.

## Read existing resources

Data sources let you read resources that Terraform doesn't manage. Most resource types have a singular data source that fetches one object and a plural data source that lists many.

| Data source                 | Required        | Optional filters                                                         | Credential      |
| :-------------------------- | :-------------- | :----------------------------------------------------------------------- | :-------------- |
| `pinecone_index`            | `name`          | —                                                                        | API key         |
| `pinecone_indexes`          | —               | —                                                                        | API key         |
| `pinecone_collection`       | `name`          | —                                                                        | API key         |
| `pinecone_collections`      | —               | —                                                                        | API key         |
| `pinecone_project`          | `id`            | —                                                                        | Service account |
| `pinecone_projects`         | —               | —                                                                        | Service account |
| `pinecone_service_account`  | `id`            | —                                                                        | Service account |
| `pinecone_service_accounts` | —               | —                                                                        | Service account |
| `pinecone_role_binding`     | `id`            | —                                                                        | Service account |
| `pinecone_role_bindings`    | —               | `principal_type`, `principal_id`, `resource_type`, `resource_id`, `role` | Service account |
| `pinecone_invite`           | `id`            | —                                                                        | Service account |
| `pinecone_invites`          | —               | —                                                                        | Service account |
| `pinecone_user`             | `id` or `email` | —                                                                        | Service account |
| `pinecone_users`            | —               | `email`                                                                  | Service account |

```terraform theme={null}
# Read one index by name
data "pinecone_index" "example_index" {
  name = "example-index"
}

# List every index in the project
data "pinecone_indexes" "all" {}

# Look up a user by email, then grant them a project role
data "pinecone_user" "example_user" {
  email = "teammate@example.com"
}

resource "pinecone_role_binding" "example_user_project_viewer" {
  principal_id   = data.pinecone_user.example_user.id
  principal_type = "user"
  resource_type  = "project"
  resource_id    = "YOUR_PROJECT_ID"
  role           = "ProjectViewer"
}

# List the role bindings held by one principal
data "pinecone_role_bindings" "example_service_account_bindings" {
  principal_type = "service_account"
  principal_id   = "YOUR_SERVICE_ACCOUNT_ID"
}
```

Note the following behaviors:

* For `pinecone_user`, set exactly one of `id` or `email`. Email matching is case-insensitive.
* For `pinecone_role_bindings`, `principal_type` is required when you set `principal_id`, and `resource_type` is required when you set `resource_id`. You can't filter by a binding's own ID. Fetch it with the `pinecone_role_binding` data source instead.
* `pinecone_invites` returns only `pending` and `expired` invites. To read an accepted invite, fetch it by ID with `pinecone_invite`.
* The service account data sources never return client secrets.

## Import existing resources

All resources support the [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import):

| Resource                   | Import ID               |
| :------------------------- | :---------------------- |
| `pinecone_index`           | Index name              |
| `pinecone_collection`      | Collection name         |
| `pinecone_project`         | Project ID              |
| `pinecone_api_key`         | `PROJECT_ID:API_KEY_ID` |
| `pinecone_service_account` | Service account ID      |
| `pinecone_role_binding`    | Role binding ID         |
| `pinecone_invite`          | Invite ID               |
| `pinecone_user`            | User ID                 |

For example:

```bash theme={null}
terraform import pinecone_user.example_user YOUR_USER_ID
```

Some attributes can't be imported because Pinecone returns them only once:

* `pinecone_api_key.key` and `pinecone_service_account.client_secret` stay empty in state for an imported resource. To issue and store a new service account secret, change `rotate_trigger`.
* `pinecone_invite.role_bindings` stays empty in state, and Terraform proposes a replacement on the next plan until you set it to match the original invite. Use the `pinecone_role_bindings` data source with `principal_type = "invite"` to see what the invite granted.

## Limitations

The Terraform Provider for Pinecone doesn't support the following:

* [Backups for serverless indexes](/guides/manage-data/backups-overview)
* [Private endpoints](/guides/production/configure-private-endpoints)
* [Assistants](/guides/assistant/overview)
* BYOC environment provisioning (you reference an existing environment by its identifier, which Pinecone provisions for you).
* Full-text search fields (the index `schema` block accepts only `filterable`, so you can't configure fields for [full-text search](/guides/search/full-text-search)).

## See also

* Documentation can be found on the [Terraform
  Registry](https://registry.terraform.io/providers/pinecone-io/pinecone/latest/docs).
* See the [GitHub repository](https://github.com/pinecone-io/terraform-provider-pinecone/tree/main/examples)
  for additional usage examples.
* For support requests, create an issue in the [GitHub
  repository](https://github.com/pinecone-io/terraform-provider-pinecone).


# Traceloop
Source: https://docs.pinecone.io/integrations/traceloop

Instrument Pinecone with Traceloop's OpenLLMetry SDK to emit OpenTelemetry traces and metrics for LLM observability in Datadog, Grafana, and more.

[Traceloop](https://www.traceloop.com/) provides observability for your LLM app using OpenTelemetry. Traceloop automatically monitors the quality of your LLM outputs. It helps you to debug and test changes to your models and prompts.

The Pinecone integration with Traceloop produces traces and metrics that can be viewed in any OpenTelemetry-based platform like Datadog, Grafana, Traceloop, and others.

<PrimarySecondaryCTA />


# TruLens
Source: https://docs.pinecone.io/integrations/trulens

Evaluate and track Pinecone RAG apps with TruLens: measure grounding, relevance, and hallucinations to iterate on vector search configurations fast.

TruLens is a powerful open source library for evaluating and tracking large language model-based applications. TruLens provides a set of tools for developing and monitoring neural nets, including large language models (LLMs). This includes both tools for evaluation of LLMs and LLM-based applications with TruLens-Eval and deep learning explainability with TruLens-Explain.

To build an effective RAG-style LLM application, it is important to experiment with various configuration choices while setting up your Pinecone vector database, and study their impact on performance metrics. Tracking and evaluation with TruLens enables fast iteration of your application.

<PrimarySecondaryCTA />

## Setup guide

[TruLens](https://github.com/truera/trulens) is a powerful open source library for evaluating and tracking large language model-based applications. In this guide, we will show you how to use TruLens to evaluate applications built on top of a high performance Pinecone vector database.

### Why TruLens?

Systematic evaluation is needed to support reliable, non-hallucinatory LLM-based applications. TruLens contains instrumentation and evaluation tools for large language model (LLM)-based applications. For evaluation, TruLens provides a set of feedback functions, analogous to labeling functions, to programmatically score the input, output and intermediate text of an LLM app. Each LLM application request can be scored on its question-answer relevance, context relevance and groundedness. These feedback functions provide evidence that your LLM-application is non-hallucinatory.

<img alt="diagram-1" />

In addition to the above, feedback functions also support the evaluation of ground truth agreement, sentiment, model agreement, language match, toxicity, and a full suite of moderation evaluations, including hate, violence and more. TruLens implements feedback functions as an extensible framework that can evaluate your custom needs as well.

During the development cycle, TruLens supports the iterative development of a wide range of LLM applications by wrapping your application to log cost, latency, key metadata and evaluations of each application run. This allows you to track and identify failure modes, pinpoint their root cause, and measure improvement across experiments.

<img alt="application-screenshot" />

### Why Pinecone?

Large language models alone have a hallucination problem. Several decades of machine learning research have optimized models, including modern LLMs, for generalization, while actively penalizing memorization. However, many of today's applications require factual, grounded answers. LLMs are also expensive to train, and provided by third party APIs. This means the knowledge of an LLM is fixed. Retrieval-augmented generation (RAG) is a way to reliably ensure models are grounded, with Pinecone as the curated source of real world information, long term memory, application domain knowledge, or whitelisted data.

In the RAG paradigm, rather than just passing a user question directly to a language model, the system retrieves any documents that could be relevant in answering the question from the knowledge base, and then passes those documents (along with the original question) to the language model to generate the final response. The most popular method for RAG involves chaining together LLMs with vector databases, such as the widely used Pinecone vector DB.

In this process, a numerical vector (an embedding) is calculated for all documents, and those vectors are then stored in a database optimized for storing and querying vectors. Incoming queries are vectorized as well, typically using an encoder LLM to convert the query into an embedding. The query embedding is then matched via embedding similarity against the document embeddings in the vector database to retrieve the documents that are relevant to the query.

<img alt="diagram-2" />

Pinecone makes it easy to build high-performance vector search applications, including retrieval-augmented question answering. Pinecone can easily handle very large scales of hundreds of millions and even billions of vector embeddings. Pinecone's large scale allows it to handle long term memory or a large corpus of rich external and domain-appropriate data so that the LLM component of RAG application can focus on tasks like summarization, inference and planning. This setup is optimal for developing a non-hallucinatory application.\
In addition, Pinecone is fully managed, so it is easy to change configurations and components. Combined with the tracking and evaluation with TruLens, this is a powerful combination that enables fast iteration of your application.

### Using Pinecone and TruLens to improve LLM performance and reduce hallucination

To build an effective RAG-style LLM application, it is important to experiment with various configuration choices while setting up the vector database, and study their impact on performance metrics.

In this example, we explore the downstream impact of some of these configuration choices on response quality, cost and latency with a sample LLM application built with Pinecone as the vector DB. The evaluation and experiment tracking is done with the [TruLens](https://www.trulens.org/) open source library. TruLens offers an extensible set of [feedback functions](https://truera.com/ai-quality-education/generative-ai-and-llms/whats-missing-to-evaluate-foundation-models-at-scale/) to evaluate LLM apps and enables developers to easily track their LLM app experiments.

In each component of this application, different configuration choices can be made that can impact downstream performance. Some of these choices include the following:

**Constructing the Vector DB**

* Data preprocessing and selection
* Chunk Size and Chunk Overlap
* Index distance metric
* Selection of embeddings

**Retrieval**

* Amount of context retrieved (top k)
* Query planning

**LLM**

* Prompting
* Model choice
* Model parameters (size, temperature, frequency penalty, model retries, etc.)

These configuration choices are useful to keep in mind when constructing your app. In general, there is no optimal choice for all use cases. Rather, we recommend that you experiment with and evaluate a variety of configurations to find the optimal selection as you are building your application.

#### Creating the index in Pinecone

Here we'll download a pre-embedded dataset from the `pinecone-datasets` library allowing us to skip the embedding and preprocessing steps.

```Python Python theme={null}
import pinecone_datasets

dataset = pinecone_datasets.load_dataset('wikipedia-simple-text-embedding-ada-002-100K')
dataset.head()
```

After downloading the data, we can initialize our pinecone environment and create our first index. Here, we have our first potentially important choice, by selecting the **distance metric** used for our index.

```Python Python theme={null}
pinecone.create_index(
        name=index_name_v1,
        metric='cosine', # We'll try each distance metric here.
        dimension=1536  # 1536 dim of text-embedding-ada-002.
)
```

Then, we can upsert our documents into the index in batches.

```Python Python theme={null}
for batch in dataset.iter_documents(batch_size=100):
    index.upsert(batch)
```

#### Build the vector store

Now that we've built our index, we can start using LangChain to initialize our vector store.

```Python Python theme={null}
embed = OpenAIEmbeddings(
    model='text-embedding-ada-002',
    openai_api_key=OPENAI_API_KEY
)

from langchain.vectorstores import Pinecone

text_field = "text"

# Switch back to a normal index for LangChain.
index = pinecone.Index(index_name_v1)

vectorstore = Pinecone(
    index, embed.embed_query, text_field
)
```

In RAG, we take the query as a question that is to be answered by an LLM, but the LLM must answer the question based on the information it receives from the `vectorstore`.

#### Initialize our RAG application

To do this, we initialize a `RetrievalQA` as our app:

```Python Python theme={null}
from langchain.chat_models import ChatOpenAI
from langchain.chains import RetrievalQA

# completion llm
llm = ChatOpenAI(
    model_name='gpt-3.5-turbo',
    temperature=0.0
)

qa = RetrievalQA.from_chain_type(
    llm=llm,
    chain_type="stuff",
    retriever=vectorstore.as_retriever()
)
```

#### TruLens for evaluation and tracking of LLM experiments

Once we've set up our app, we should put together our [feedback functions](https://truera.com/ai-quality-education/generative-ai-and-llms/whats-missing-to-evaluate-foundation-models-at-scale/). As a reminder, feedback functions are an extensible method for evaluating LLMs. Here we'll set up two feedback functions: `qs_relevance` and `qa_relevance`. They're defined as follows:

*QS Relevance: query-statement relevance is the average of relevance (0 to 1) for each context chunk returned by the semantic search.*
*QA Relevance: question-answer relevance is the relevance (again, 0 to 1) of the final answer to the original question.*

```Python Python theme={null}
# Imports main tools for eval
from trulens_eval import TruChain, Feedback, Tru, feedback, Select
import numpy as np
tru = Tru()

# OpenAI as feedback provider
openai = feedback.OpenAI()

# Question/answer relevance between overall question and answer.
qa_relevance = Feedback(openai.relevance).on_input_output()

# Question/statement relevance between question and each context chunk.
qs_relevance = (
    Feedback(openai.qs_relevance)
    .on_input()
    # See explanation below 
    .on(Select.Record.app.combine_documents_chain._call.args.inputs.input_documents[:].page_content)
    .aggregate(np.mean)
)

```

Our use of selectors here also requires an explanation.

QA Relevance is the simpler of the two. Here, we are using `.on_input_output()` to specify that the feedback function should be applied on both the input and output of the application.

For QS Relevance, we use TruLens selectors to locate the context chunks retrieved by our application. Let's break it down into simple parts:

1. Argument Specification – The `on_input` which appears first is a convenient shorthand and states that the first argument to `qs_relevance` (the question) is to be the main input of the app.

2. Argument Specification – The `on(Select...)` line specifies where the statement argument to the implementation comes from. We want to evaluate the context chunks, which are an intermediate step of the LLM app. This form references the langchain app object call chain, which can be viewed from `tru.run_dashboard()`. This flexibility allows you to apply a feedback function to any intermediate step of your LLM app. Below is an example where TruLens displays how to select each piece of the context.

   <img alt="subcomponents" />

3. Aggregation specification -- The last line aggregate (`np.mean`) specifies how feedback outputs are to be aggregated. This only applies to cases where the argument specification names more than one value for an input or output.

The result of these lines is that `f_qs_relevance` can be now be run on apps/records and will automatically select the specified components of those apps/records

To finish up, we just wrap our Retrieval QA app with TruLens along with a list of the feedback functions we will use for eval.

```Python Python theme={null}
# wrap with TruLens
truchain = TruChain(qa,
    app_id='Chain1_WikipediaQA',
    feedbacks=[qa_relevance, qs_relevance])

truchain("Which state is Washington D.C. in?")
```

After submitting a number of queries to our application, we can track our experiment and evaluations with the TruLens dashboard.

```Python Python theme={null}
tru.run_dashboard()
```

Here is a view of our first experiment:

<img alt="trulens-dashboard-1" />

#### Experiment with distance metrics

Now that we've walked through the process of building our tracked RAG application using cosine as the distance metric, all we have to do for the next two experiments is to rebuild the index with `euclidean` or `dotproduct` as the metric and follow the rest of the steps above as is.

Because we are using OpenAI embeddings, which are normalized to length 1, dot product and cosine distance are equivalent - and Euclidean will also yield the same ranking. See the OpenAI docs for more information. With the same document ranking, we should not expect a difference in response quality, but computation latency may vary across the metrics. Indeed, OpenAI advises that dot product computation may be a bit faster than cosine. We will be able to confirm this expected latency difference with TruLens.

```Python Python theme={null}
index_name_v2 = 'langchain-rag-euclidean'
pinecone.create_index(
        name=index_name_v2,
        metric='euclidean', # metric='dotproduct',
        dimension=1536,  # 1536 dim of text-embedding-ada-002
    )
```

After doing so, we can view our evaluations for all three LLM apps sitting on top of the different indexes. All three apps are struggling with query-statement relevance. In other words, the context retrieved is only somewhat relevant to the original query.

**We can also see that both the Euclidean and dot-product metrics performed at a lower latency than cosine at roughly the same evaluation quality.**

<img alt="trulens-dashboard-2" />

### Problem: hallucination

Digging deeper into the Query Statement Relevance, we notice one problem in particular with a question about famous dental floss brands. The app responds correctly, but is not backed up by the context retrieved, which does not mention any specific brands.

<img alt="trulens-dashboard-feedback-1" />

#### Quickly evaluate app components with LangChain and TruLens

Using a less powerful model is a common way to reduce hallucination for some applications. We'll evaluate ada-001 in our next experiment for this purpose.

<img alt="trulens-dashboard-3" />

Changing different components of apps built with frameworks like LangChain is really easy. In this case we just need to call `text-ada-001` from the LangChain LLM store. Adding in easy evaluation with TruLens allows us to quickly iterate through different components to find our optimal app configuration.

```Python Python theme={null}
# completion llm
from langchain.llms import OpenAI

llm = OpenAI(
    model_name='text-ada-001',
    temperature=0
)

from langchain.chains import RetrievalQAWithSourcesChain
qa_with_sources = RetrievalQA.from_chain_type(
    llm=llm,
    chain_type="stuff",
    retriever=vectorstore.as_retriever()
)

# wrap with TruLens
truchain = TruChain(qa_with_sources,
    app_id='Chain4_WikipediaQA',
    feedbacks=[qa_relevance, qs_relevance])
```

**However, this configuration with a less powerful model struggles to return a relevant answer given the context provided.**

<img alt="trulens-dashboard-4" />

For example, when asked “Which year was Hawaii's state song written?”, the app retrieves context that contains the correct answer but fails to respond with that answer, instead simply responding with the name of the song.

<img alt="trulens-dashboard-feedback-2" />

While our relevance function is not doing a great job here in differentiating which context chunks are relevant, we can manually see that only the one (the 4th chunk) mentions the year the song was written. Narrowing our `top_k`, or the number of context chunks retrieved by the semantic search, may help.

We can do so as follows:

```Python Python theme={null}
qa = RetrievalQA.from_chain_type(
    llm=llm,
    chain_type="stuff",
    retriever=vectorstore.as_retriever(top_k = 1)
)
```

The way the `top_k` is implemented in LangChain's RetrievalQA is that the documents are still retrieved by semantic search and only the `top_k` are passed to the LLM. Therefore, TruLens also captures all of the context chunks that are being retrieved. In order to calculate an accurate QS Relevance metric that matches what's being passed to the LLM, we only calculate the relevance of the top context chunk retrieved by slicing the `input_documents` passed into the TruLens Select function:

```Python Python theme={null}
qs_relevance = Feedback(openai.qs_relevance).on_input().on(
    Select.Record.app.combine_documents_chain._call.args.inputs.input_documents[:1].page_content
).aggregate(np.mean)
```

Once we've done so, our final application has much improved `qs_relevance`, `qa_relevance` and latency!

<img alt="trulens-dashboard-5" />

With that change, our application is successfully retrieving the one piece of context it needs, and successfully forming an answer from that context.

<img alt="trulens-dashboard-feedback-3" />

Even better, the application now knows what it doesn't know:

<img alt="trulens-dashboard-feedback-4" />

### Summary

In conclusion, we note that exploring the downstream impact of some Pinecone configuration choices on response quality, cost and latency is an important part of the LLM app development process, ensuring that we make the choices that lead to the app performing the best. Overall, TruLens and Pinecone are the perfect combination for building reliable RAG-style applications. Pinecone provides a way to efficiently store and retrieve context used by LLM apps, and TruLens provides a way to track and evaluate each iteration of your application.


# Twelve Labs
Source: https://docs.pinecone.io/integrations/twelve-labs

Store Twelve Labs multimodal video embeddings in Pinecone to power video search, recommendations, and content moderation with fast similarity retrieval.

[Twelve Labs](https://twelvelabs.io) is an AI company that provides state-of-the-art video understanding capabilities through its easy-to-use APIs. Our newly released product is the Embed API, which enables developers to create high-quality multimodal embeddings that capture the rich context and interactions between different modalities in videos, such as visual expressions, body language, spoken words, and overall context.

By integrating Twelve Labs' Embed API with Pinecone's vector database, developers can efficiently store, index, and retrieve these multimodal embeddings at scale. This integration empowers developers to build cutting-edge AI applications that leverage video data, such as video search, recommendation systems, content moderation, and more. Developers can seamlessly generate embeddings using Twelve Labs' API and store them in Pinecone for fast and accurate similarity search and retrieval.

The integration of Twelve Labs and Pinecone offers developers a powerful toolkit to process and understand video content in a more human-like manner. By combining Twelve Labs' video-native approach with Pinecone's purpose-built vector search capabilities, developers can unlock new possibilities and build innovative applications across various industries, including media and entertainment, e-commerce, education, and beyond.

<PrimarySecondaryCTA />

## Setup guide

To integrate Twelve Labs' Embed API with Pinecone:

1. Sign up for a [Twelve Labs](https://twelvelabs.io) and obtain your API key.
2. Install the [Twelve Labs Python client library](https://github.com/twelvelabs-io/twelvelabs-python).
3. Sign up for a [Pinecone account](https://app.pinecone.io/) and [create an index](/guides/index-data/create-an-index).
4. Install the [Pinecone client library](/reference/pinecone-sdks).
5. Use the [Twelve Labs Embed API](https://docs.twelvelabs.io/docs/create-embeddings) to generate multimodal embeddings for your videos.
6. Connect to your Pinecone index and [upsert the embeddings](/guides/index-data/upsert-data).
7. [Query the Pinecone index](/guides/search/search-overview) to retrieve similar videos based on embeddings.

For more detailed information and code examples, please see the [Twelve Labs documentation](https://docs.twelvelabs.io).


# Unstructured
Source: https://docs.pinecone.io/integrations/unstructured

Use Unstructured to parse, chunk, and load PDFs, Word, and 25+ document types into Pinecone for LLM-ready RAG ETL pipelines and semantic search apps.

Unstructured builds ETL tools for LLMs, including an open source Python library, a SaaS API, and an ETL platform. Unstructured extracts content and metadata from 25+ document types, including PDFs, Word documents and PowerPoints. After extracting content and metadata, Unstructured performs additional preprocessing steps for LLMs such as chunking. Unstructured maintains upstream connections to data sources such as SharePoint and Google drive, and downstream connections to databases such as Pinecone.

Integrating Pinecone with Unstructured enables developers to load data from an source or document type into Pinecone with a single click, accelerating the building of LLM apps that connect to organizational data.

<PrimarySecondaryCTA />


# Vercel
Source: https://docs.pinecone.io/integrations/vercel

Deploy AI apps on Vercel with Pinecone as long-term memory: one-click setup, scalable vector search, and RAG for Next.js and edge-deployed frontends.

Vercel is a platform for developers that provides the tools, workflows, and infrastructure you need to build and deploy your web apps faster, without the need for additional configuration. Vercel supports popular frontend frameworks out-of-the-box, and its scalable, secure infrastructure is globally distributed to serve content from data centers near your users for optimal speeds.

Pinecone provides the long-term memory for your Vercel AI projects. Using Pinecone with Vercel enables you to quickly set up and authenticate a connection to your Pinecone data/indexes, and then easily scale to support billions of data points. The integration is designed to be self-serve with strong defaults for a smooth setup, with optional advanced settings.

<PrimarySecondaryCTA />


# VoltAgent
Source: https://docs.pinecone.io/integrations/voltagent

Build TypeScript AI agents with VoltAgent and Pinecone: automatic embeddings, semantic search, metadata filtering, and observable RAG in production.

[VoltAgent](https://voltagent.dev) is a TypeScript-based, AI-agent framework for building production-ready applications with retrieval-augmented generation (RAG) capabilities. It supports two retrieval patterns: automatic search on every interaction, or LLM-decides-when-to-search, with built-in observability and tracking.

This integration connects VoltAgent agents to Pinecone's managed vector database, automatically generating embeddings with OpenAI's API. It provides semantic search with similarity scoring, source tracking, metadata filtering, and namespace organization, and it supports serverless deployment with automatic scaling.

The integration provides:

* A complete RAG setup with sample data
* Two pre-configured agent types
* Automatic index creation and population
* Source references and similarity scores
* Production-ready architecture

Use this integration to quickly build AI agents that can intelligently search and retrieve information from Pinecone vector databases, while maintaining full observability and control over the retrieval process.

<PrimarySecondaryCTA />


# Voyage AI
Source: https://docs.pinecone.io/integrations/voyage

Generate top-ranked Voyage AI embeddings and rerankers, then index them in Pinecone for high-accuracy RAG, semantic search, and code retrieval apps.

[Voyage AI](https://www.voyageai.com) provides cutting-edge embedding and rerankers. Voyage AI's generalist [embedding models](https://docs.voyageai.com/docs/embeddings) continually top the [MTEB leaderboard](https://huggingface.co/spaces/mteb/leaderboard), and the [domain-specific embeddings](https://blog.voyageai.com/2024/01/23/voyage-code-2-elevate-your-code-retrieval/) enhance the retrieval quality for enterprise use cases significantly.

<PrimarySecondaryCTA />

## Setup guide

In this guide, we use the [Voyage Embedding API endpoint](https://docs.voyageai.com/docs/embeddings) to generate text embeddings for terms of service and consumer contract documents, and then index those embeddings in the Pinecone vector database.

This is a powerful and common combination for building retrieval-augmented generation (RAG), semantic search, question-answering, code assistants, and other applications that rely on NLP and search over a large corpus of text data.

### 1. Set up the environment

Start by installing the Voyage and Pinecone clients and HuggingFace *Datasets* for downloading the *LegalBench: Consumer Contracts QA* ([`mteb/legalbench_consumer_contracts_qa`](https://huggingface.co/datasets/mteb/legalbench_consumer_contracts_qa)) dataset used in this guide:

```shell Shell theme={null}
pip install -U voyageai pinecone[grpc] datasets
```

### 2. Create embeddings

Sign up for an API key at [Voyage AI](https://dash.voyageai.com) and then use it to initialize your connection.

```Python Python theme={null}
import voyageai

vc = voyageai.Client(api_key="<YOUR_VOYAGE_API_KEY>")
```

Load the *LegalBench: Consumer Contracts QA*  dataset, which contains 154 consumer contract documents and 396 labeled queries about these documents.

```Python Python theme={null}
from datasets import load_dataset

# load the documents and queries of legalbench consumer contracts qa dataset
documents = load_dataset('mteb/legalbench_consumer_contracts_qa', 'corpus', cache_dir = './', split='corpus')
queries = load_dataset('mteb/legalbench_consumer_contracts_qa', 'queries', cache_dir = './', split='queries')

```

Each document in `mteb/legalbench_consumer_contracts_qa` contains a `text` field by which we will embed using the Voyage AI client.

```Python Python theme={null}
num_documents = len(documents['text'])
voyageai_batch_size = 128  # Please check the restrictions of number of examples and number of tokens per request here https://docs.voyageai.com/docs/embeddings
embeds = []
while len(embeds) < num_documents:
    embeds.extend(vc.embed(
        texts=documents['text'][len(embeds):len(embeds)+voyageai_batch_size],
        model='voyage-law-2',  # Please check the available models here https://docs.voyageai.com/docs/embeddings
        input_type='document',
        truncation=True
    ).embeddings)
```

Check the dimensionality of the returned vectors. You will need to save the embedding dimensionality from this to be used when initializing your Pinecone index later.

```Python Python theme={null}
import numpy as np

shape = np.array(embeds).shape
print(shape)
```

```
[Out]:
(154, 1024)
```

In this example, you can see that for each of the `154` documents, we created a `1024`-dimensional embedding with the Voyage AI `voyage-law-2` model.

### 3. Store the Embeddings

Now that you have your embeddings, you can move on to indexing them in the Pinecone vector database. For this, you need a Pinecone API key. [Sign up for one here](https://app.pinecone.io).

You first initialize our connection to Pinecone and then create a new index called `voyageai-pinecone-legalbench` for storing the embeddings. When creating the index, you specify that you would like to use the cosine similarity metric to align with Voyage AI's embeddings, and also pass the embedding dimensionality of `1024`.

```Python Python theme={null}
from pinecone.grpc import PineconeGRPC as Pinecone
from pinecone import ServerlessSpec

# initialize connection to pinecone (get API key at app.pinecone.io)
pc = Pinecone(api_key="<YOUR_PINECONE_API_KEY>")

index_name = 'voyageai-pinecone-legalbench'

# if the index does not exist, we create it
if not pc.has_index(index_name):
    pc.create_index(
        index_name,
        dimension=shape[1],
        spec=ServerlessSpec(
            cloud='aws',
            region='us-east-1'
        ),
        metric='cosine'
    )

# connect to index
index = pc.Index(index_name)
```

Now you can begin populating the index with your embeddings. Pinecone expects you to provide a list of tuples in the format (`id`, `vector`, `metadata`), where the `metadata` field is an optional extra field where you can store anything you want in a dictionary format. For this example, you will store the original text of the embeddings.

While uploading your data, you will batch everything to avoid pushing too much data in one go.

```Python Python theme={null}
batch_size = 128

ids = [str(i) for i in range(shape[0])]
# create list of metadata dictionaries
meta = [{'text': text} for text in documents['text']]

# create list of (id, vector, metadata) tuples to be upserted
to_upsert = list(zip(ids, embeds, meta))

for i in range(0, shape[0], batch_size):
    i_end = min(i+batch_size, shape[0])
    index.upsert(vectors=to_upsert[i:i_end])

# let's view the index statistics
print(index.describe_index_stats())
```

```
[Out]:
{'dimension': 1024,
 'index_fullness': 0.0,
 'namespaces': {'': {'vector_count': 154}},
 'total_vector_count': 154}
```

You can see from `index.describe_index_stats` that you have a *1024-dimensionality* index populated with *154* embeddings. The `indexFullness` metric tells you how full your index is. At the moment, it is empty. Using the default value of one *p1* pod, you can fit around 750K embeddings before the `indexFullness` reaches capacity. The [Usage Estimator](https://www.pinecone.io/pricing/) can be used to identify the number of pods required for a given number of *n*-dimensional embeddings.

### 4. Semantic search

Now that you have your indexed vectors, you can perform a few search queries. When searching, you will first embed your query using `voyage-law-2`, and then search using the returned vector in Pinecone.

```Python Python theme={null}
# get a sample query from the dataset, "Will Google help me if I think someone has taken and used content Ive created without my permission?" 
query = queries['text'][0]
print(f"Query: {query}")

# create the query embedding
xq = vc.embed(
    texts=[query],
    model='voyage-law-2',
    input_type="query",
    truncation=True
).embeddings

# query, returning the top 3 most similar results
res = index.query(vector=xq, top_k=3, include_metadata=True)
```

The response from Pinecone includes your original text in the `metadata` field. Let's print out the `top_k` most similar questions and their respective similarity scores.

```Python Python theme={null}
for match in res['matches']:
    print(f"{match['score']:.2f}: {match['metadata']['text']}")
```

```
[Out]:
0.59: Your content
Some of our services give you the opportunity to make your content publicly available  for example, you might post a product or restaurant review that you wrote, or you might upload a blog post that you created.
See the Permission to use your content section for more about your rights in your content, and how your content is used in our services
See the Removing your content section to learn why and how we might remove user-generated content from our services
If you think that someone is infringing your intellectual property rights, you can send us notice of the infringement and well take appropriate action. For example, we suspend or close the Google Accounts of repeat copyright infringers as described in our Copyright Help Centre.


0.47: Google content
Some of our services include content that belongs to Google  for example, many of the visual illustrations that you see in Google Maps. You may use Googles content as allowed by these terms and any service-specific additional terms, but we retain any intellectual property rights that we have in our content. Dont remove, obscure or alter any of our branding, logos or legal notices. If you want to use our branding or logos, please see the Google Brand Permissions page.

Other content
Finally, some of our services gives you access to content that belongs to other people or organisations  for example, a store owners description of their own business, or a newspaper article displayed in Google News. You may not use this content without that person or organisations permission, or as otherwise allowed by law. The views expressed in the content of other people or organisations are their own, and dont necessarily reflect Googles views.


0.45: Taking action in case of problems
Before taking action as described below, well provide you with advance notice when reasonably possible, describe the reason for our action and give you an opportunity to fix the problem, unless we reasonably believe that doing so would:
cause harm or liability to a user, third party or Google
violate the law or a legal enforcement authoritys order
compromise an investigation
compromise the operation, integrity or security of our services

Removing your content
If we reasonably believe that any of your content (1) breaches these terms, service-specific additional terms or policies, (2) violates applicable law, or (3) could harm our users, third parties or Google, then we reserve the right to take down some or all of that content in accordance with applicable law. Examples include child pornography, content that facilitates human trafficking or harassment, and content that infringes someone elses intellectual property rights.

Suspending or terminating your access to Google services
Google reserves the right to suspend or terminate your access to the services or delete your Google Account if any of these things happen:
you materially or repeatedly breach these terms, service-specific additional terms or policies
were required to do so to comply with a legal requirement or a court order
we reasonably believe that your conduct causes harm or liability to a user, third party or Google  for example, by hacking, phishing, harassing, spamming, misleading others or scraping content that doesnt belong to you
If you believe that your Google Account has been suspended or terminated in error, you can appeal.
Of course, youre always free to stop using our services at any time. If you do stop using a service, wed appreciate knowing why so that we can continue improving our services.

```

The semantic search pipeline with Voyage AI and Pinecone is able to identify the relevant consumer contract documents to answer the user query.


# Zapier
Source: https://docs.pinecone.io/integrations/zapier

Automate Pinecone with Zapier: trigger workflows on index changes, upsert data from spreadsheets, and connect vector search to 6,000+ no-code apps.

[Zapier](https://zapier.com/) lets you connect Pinecone with thousands of the most popular apps, so you can automate your work and have more time for what matters most — no code required.

With this integration, Pinecone can trigger workflows when your index status changes, and other apps can command Pinecone to perform actions. This means you can automatically add or remove data, run searches, or manage indexes based on events happening in your other tools.

For example, you might use this integration to automatically add spreadsheet entries to your Pinecone index, or build a bot that searches for answers and posts them directly to your team chat. It's all about weaving Pinecone's powerful search and data capabilities into your existing workflows, making everything work together automatically.

<PrimarySecondaryCTA />


# 2022 releases
Source: https://docs.pinecone.io/release-notes/2022

Pinecone release notes for 2022: new features, improvements, and API changes.

## December 22, 2022

#### Pinecone is now available in Google Cloud Marketplace

You can now [sign up for Pinecone billing through Google Cloud Marketplace](/guides/organizations/manage-billing/upgrade-billing-plan).

## December 6, 2022

#### Organizations are generally available

Pinecone now features [organizations](/guides/organizations/understanding-organizations), which allow one or more users to control billing and project settings across multiple projects owned by the same organization.

#### p2 pod type is generally available

The [p2 pod type](/guides/index-data/indexing-overview#p2-pods) is now generally available and ready for production workloads. p2 pods are now available in the Starter plan and support the [dotproduct distance metric](/guides/index-data/create-an-index#dotproduct).

#### Performance improvements

* [Bulk vector\_deletes](/guides/index-data/upsert-data/#deleting-vectors) are now up to 10x faster in many circumstances.
* [Creating collections](/guides/manage-data/back-up-an-index) is now faster.

## October 31, 2022

#### Hybrid search (Early access)

Pinecone now supports keyword-aware semantic search with the new hybrid search indexes and endpoints. Hybrid search enables improved relevance for semantic search results by combining them with keyword search.

This is an **early access** feature and is available only by [signing up](https://www.pinecone.io/hybrid-search-early-access/).

## October 17, 2022

#### Status page

The new [Pinecone Status Page](https://status.pinecone.io/) displays information about the status of the Pinecone service, including the status of individual cloud regions and a log of recent incidents.

## September 16, 2022

#### Public collections

You can now create indexes from public collections, which are collections containing public data from real-world data sources. Currently, public collections include the Glue - SSTB collection, the TREC Question classification collection, and the SQuAD collection.

## August 16, 2022

#### Collections (Public preview)("Beta")

You can now \[make static copies of your index]\(/guides/manage-data/back-up-an-index using collections]\(/guides/manage-data/back-up-an-index#pod-based-index-backups-using-collections). After you create a collection from an index, you can create a new index from that collection. The new index can use any pod type and any number of pods. Collections only consume storage.

This is a **public preview** feature and is not appropriate for production workloads.

#### Vertical scaling

You can now [change the size of the pods](/guides/indexes/pods/scale-pod-based-indexes#increase-pod-size) for a live index to accommodate more vectors or queries without interrupting reads or writes. The p1 and s1 pod types are now available in [4 different sizes](/guides/index-data/indexing-overview/#pods-pod-types-and-pod-sizes): `1x`, `2x`, `4x`, and `8x`. Capacity and compute per pod double with each size increment.

#### p2 pod type (Public preview)("Beta")

The new [p2 pod type](/guides/index-data/indexing-overview/#p2-pods) provides search speeds of around 5ms and throughput of 200 queries per second per replica, or approximately 10x faster speeds and higher throughput than the p1 pod type, depending on your data and network conditions.

This is a **public preview** feature and is not appropriate for production workloads.

#### Improved p1 and s1 performance

The [s1](/guides/index-data/indexing-overview/#s1-pods) and [p1](/guides/index-data/indexing-overview/#p1-pods) pod types now offer approximately 50% higher query throughput and 50% lower latency, depending on your workload.

## July 26, 2022

You can now specify a [metadata filter](/guides/index-data/indexing-overview#metadata/) to get results for a subset of the vectors in your index by calling [describe\_index\_stats](/reference/api/2024-07/control-plane/describe_index) with a [filter](/reference/api/2024-07/control-plane/describe_index#!path=filter\&t=request) object.

The `describe_index_stats` operation now uses the `POST` HTTP request type. The `filter` parameter is only accepted by `describe_index_stats` calls using the `POST` request type. Calls to `describe_index_stats` using the `GET` request type are now deprecated.

## July 12, 2022

#### Pinecone Console Guided Tour

You can now choose to follow a guided tour in the [Pinecone console](https://app.pinecone.io). This interactive tutorial walks you through creating your first index, upserting vectors, and querying your data. The purpose of the tour is to show you all the steps you need to start your first project in Pinecone.

## June 24, 2022

#### Updated response codes

The [create\_index](/reference/api/2024-07/control-plane/create_index), [delete\_index](/reference/api/2024-07/control-plane/delete_index), and `scale_index` operations now use more specific HTTP response codes that describe the type of operation that succeeded.

## June 7, 2022

#### Selective metadata indexing

You can now store more metadata and more unique metadata values! [Select which metadata fields you want to index for filtering](/guides/indexes/pods/manage-pod-based-indexes#selective-metadata-indexing) and which fields you only wish to store and retrieve. When you index metadata fields, you can filter vector search queries using those fields. When you store metadata fields without indexing them, you keep memory utilization low, especially when you have many unique metadata values, and therefore can fit more vectors per pod.

#### Single-vector queries

You can now [specify a single query vector using the vector input](/reference/api/2024-07/data-plane/query/#!path=vector\&t=request). We now encourage all users to query using a single vector rather than a batch of vectors, because batching queries can lead to long response messages and query times, and single queries execute just as fast on the server side.

#### Query by ID

You can now [query your Pinecone index using only the ID for another vector](/reference/api/2024-07/data-plane/query/#!path=id\&t=request). This is useful when you want to search for the nearest neighbors of a vector that is already stored in Pinecone.

#### Improved index fullness accuracy

The index fullness metric in [describe\_index\_stats()](/reference/api/2024-07/control-plane/describe_index#!c=200\&path=indexFullness\&t=response) results is now more accurate.

## April 25, 2022

#### Partial updates (Public preview)

You can now perform a partial update by ID and individual value pairs. This allows you to update individual metadata fields without having to upsert a matching vector or update all metadata fields at once.

#### New metrics

Users on all plans can now see metrics for the past one (1) week in the Pinecone console. Users on the Enterprise plan now have access to the following metrics via the [Prometheus metrics endpoint](/guides/production/monitoring/):

* `pinecone_vector_count`
* `pinecone_request_count_total`
* `pinecone_request_error_count_total`
* `pinecone_request_latency_seconds`
* `pinecone_index_fullness` (Public preview)

**Note:** The accuracy of the `pinecone_index_fullness` metric is improved. This may result in changes from historic reported values. This metric is in public preview.

#### Spark Connector

Spark users who want to manage parallel upserts into Pinecone can now use the [official Spark connector for Pinecone](https://github.com/pinecone-io/spark-pinecone#readme) to upsert their data from a Spark dataframe.

#### Support for Boolean and float metadata in Pinecone indexes

You can now add `Boolean` and `float64` values to [metadata JSON objects associated with a Pinecone index.](/guides/index-data/indexing-overview#metadata)

#### New state field in describe\_index results

The [describe\_index](/reference/api/2024-07/control-plane/describe_index/) operation results now contain a value for `state`, which describes the state of the index. The possible values for `state` are `Initializing`, `ScalingUp`, `ScalingDown`, `Terminating`, and `Ready`.

##### Delete by metadata filter

The [Delete](/reference/api/2024-07/data-plane/delete/) operation now supports filtering my metadata.


# 2023 releases
Source: https://docs.pinecone.io/release-notes/2023

Pinecone release notes for 2023: new features, improvements, and API changes.

## December 2023

### Features

* The free Starter plan now supports up to 100 namespaces. [Namespaces](/guides/index-data/indexing-overview#namespaces) let you partition vectors within an index to speed up queries or comply with [multitenancy](/guides/index-data/implement-multitenancy) requirements.

## November 2023

### Features

* The new [Pinecone AWS Reference Architecture](https://github.com/pinecone-io/aws-reference-architecture-pulumi/tree/main) is an open-source, distributed system that performs vector-database-enabled semantic search over Postgres records. You can use it as a learning resource or as a starting point for high-scale use cases.

### SDKs

* [Canopy](https://github.com/pinecone-io/canopy/blob/main/README.md) is a new open-source Retrieval Augmented Generation (RAG) framework and context engine built on top of Pinecone. It enables you to start chatting with your documents or text data with a few simple commands.\
  The latest version of the Canopy SDK (v0.2.0) adds support for OpenAI SDK v1.2.3. See the [release notes](https://github.com/pinecone-io/canopy/releases/tag/V0.2.0) in GitHub for more details.

### Billing

* Pinecone is now registered to collect Value Added Tax (VAT) or Goods and Services Tax (GST) for accounts based in various global regions. If applicable, add your VAT or GST number to your account under **Settings > Billing**.

### October 2023

### Features

* [Collections](/guides/manage-data/back-up-an-index#pod-based-index-backups-using-collections) are now generally available (GA).

### Regions

* Pinecone Azure support via the [‘eastus-azure\` region](/guides/projects/understanding-projects#project-environments) is now generally available (GA).

### SDKs

* The latest version of our Node SDK is v1.1.2. See the [release notes](https://github.com/pinecone-io/pinecone-ts-client/releases/tag/v1.1.2) in GitHub for more details.

### Console

* The Index Browser is now available in the console. This allows you to preview, query, and filter by metadata directly from the console. The Index Browser can be found within the index detail page.
* We’re improved the design of our metrics page to include new charts for record and error count plus additional latencies (p90, p99) to help triage and understand issues.

### Integrations

* Knowledge Base for Amazon Bedrock is now available in private preview. Integrate your enterprise data via retrieval augmented generation (RAG) when building search and GenAI applications. [Learn more](https://www.pinecone.io/blog/amazon-bedrock-integration/).
* Pinecone Sink Connector for Confluent is now available in public preview. Gain access to data streams from across your business to build a real-time knowledge base for your AI applications. [Learn more](https://www.pinecone.io/confluent-integration).

### Billing

* You can now [sign up for Pinecone billing through Microsoft Marketplace](/guides/organizations/manage-billing/upgrade-billing-plan).

### Privacy

* Pinecone is now HIPAA compliant across all of our cloud providers (AWS, Azure, and GCP).

## September 11, 2023

Pinecone Azure support via the [eastus-azure region](/guides/projects/understanding-projects#project-environments) is now generally available (GA).

## August 14, 2023

Pinecone now supports deploying projects to Azure using the new [eastus-azure region](/guides/projects/understanding-projects#project-environments). This is a public preview environment, so test thoroughly before deploying to production.

## June 21, 2023

The new `gcp-starter` region is now in public preview. This region has distinct limitations from other Starter Plan regions. `gcp-starter` is the default region for some new users.

## April 26, 2023

[Indexes in the starter plan](/guides/index-data/indexing-overview#starter-plan) now support approximately 100,000 1536-dimensional embeddings with metadata. Capacity is proportional for other dimensionalities.

## April 3, 2023

Pinecone now supports [new US and EU cloud regions](/guides/projects/understanding-projects#project-environments).

## March 21, 2023

Pinecone now supports SSO on some Enterprise plans. [Contact Support](https://app.pinecone.io/organizations/-/settings/support) to set up your integration.

## March 1, 2023

Pinecone now supports [40kb of metadata per vector](/guides/index-data/indexing-overview#metadata#supported-metadata-size).

## February 22, 2023

#### Sparse-dense embeddings are now in public preview.

Pinecone now supports [vectors with sparse and dense values](/guides/search/hybrid-search#use-a-single-index-for-dense-and-sparse-vectors). To use sparse-dense embeddings in Python, upgrade to Python SDK version 2.2.0.

#### Pinecone Python SDK version 2.2.0 is available

Python SDK version 2.2.0 with support for sparse-dense embeddings is now available on [GitHub](https://github.com/pinecone-io/pinecone-python-client) and [PYPI](https://pypi.org/project/pinecone-client/2.2.0/).

## February 15, 2023

#### New Node.js SDK is now available in public preview

You can now try out our new [Node.js SDK for Pinecone](https://sdk.pinecone.io/typescript/).

## February 14, 2023

#### New usage reports in the Pinecone console

You can now monitor your current and projected Pinecone usage with the [**Usage** dashboard](/guides/manage-cost/monitor-usage-and-costs).

## January 31, 2023

#### Pinecone is now available in AWS Marketplace

You can now [sign up for Pinecone billing through Amazon Web Services Marketplace](/guides/organizations/manage-billing/upgrade-billing-plan).

## January 3, 2023

#### Pinecone Python SDK version 2.1.0 is now available on GitHub.

The [latest release of the Python SDK](https://github.com/pinecone-io/pinecone-python-client/releases/tag/2.1.0) makes the following changes:

* Fixes "Connection Reset by peer" error after long idle periods
* Adds typing and explicit names for arguments in all client operations
* Adds docstrings to all client operations
* Adds Support for batch upserts by passing `batch_size` to the upsert method
* Improves gRPC query results parsing performance


# 2024 releases
Source: https://docs.pinecone.io/release-notes/2024

Pinecone release notes for 2024: new features, improvements, and API changes.

## December 2024

<Update label="2024-12-23">
  ### Increased namespaces limit

  Customers on the [Standard plan](https://www.pinecone.io/pricing/) can now have up to 25,000 namespaces per index.
</Update>

<Update label="2024-12-19">
  ### Pinecone Assistant JSON mode and EU region deployment

  Pinecone Assistant can now [return a JSON response](/guides/assistant/chat-with-assistant#json-response).

  ***

  You can now [create an assistant](/reference/api/2025-01/assistant/create_assistant) in the `eu` region.
</Update>

<Update label="2024-12-17">
  ### Released Spark-Pinecone connector v1.2.0

  Released [`v1.2.0`](https://github.com/pinecone-io/spark-pinecone/releases/tag/v1.2.0) of the [Spark-Pinecone connector](/reference/tools/pinecone-spark-connector). This version introduces support for stream upserts with structured streaming. This enhancement allows users to seamlessly stream data into Pinecone for upsert operations.
</Update>

<Update label="2024-12-10">
  ### New integration with HoneyHive

  Added the [HoneyHive](/integrations/honeyhive) integration page.
</Update>

<Update label="2024-12-09">
  ### Released Python SDK v5.4.2

  Released [`v5.4.2`](https://github.com/pinecone-io/pinecone-python-client/releases/tag/v5.4.2) of the [Pinecone Python SDK](/reference/sdks/python/overview). This release adds a required keyword argument, `metric`, to the `query_namespaces` method. This change enables the SDK to merge results no matter how many results are returned.
</Update>

<Update label="2024-12-06">
  <img />

  ### Launch week: Pinecone Local

  Pinecone now offers Pinecone Local, an in-memory database emulator available as a Docker image. You can use Pinecone Local to [develop your applications locally](/guides/operations/local-development), or to [test your applications in CI/CD](/guides/production/automated-testing), without connecting to your Pinecone account, affecting production data, or incurring any usage or storage fees. Pinecone Local is in [public preview](/release-notes/feature-availability).
</Update>

<Update label="2024-12-05">
  ### Launch week: Enhanced security and access controls

  Support for [customer-managed encryption keys (CMEK)](/guides/production/configure-cmek) is now in [public preview](/release-notes/feature-availability).

  ***

  You can now [change API key permissions](/guides/projects/manage-api-keys#update-an-api-key).

  ***

  Private Endpoints are now in [general availability](/release-notes/feature-availability). Use Private Endpoints to [connect AWS PrivateLink](/guides/production/configure-private-endpoints) to Pinecone while keeping your VPC private from the public internet.

  ***

  [Audit logs](/guides/production/security-overview#audit-logs), now in early access, provide a detailed record of user and API actions that occur within the Pinecone platform.
</Update>

<Update label="2024-12-04">
  ### Launch week: `pinecone-rerank-v0` and `cohere-rerank-3.5` on Pinecone Inference

  Released [`pinecone-rerank-v0`](/guides/search/rerank-results#pinecone-rerank-v0), Pinecone's state of the art reranking model that out-performs competitors on widely accepted benchmarks. This model is in [public preview](/release-notes/feature-availability).

  ***

  Pinecone Inference now hosts [`cohere-rerank-3.5`](/guides/search/rerank-results#cohere-rerank-3.5), Cohere's leading reranking model.
</Update>

<Update label="2024-12-03">
  ### Launch week: Integrated Inference

  You can now use [embedding models](/guides/index-data/create-an-index#embedding-models) and [reranking models](/guides/search/rerank-results#reranking-models) hosted on Pinecone as an integrated part of upserting and searching.
</Update>

<Update label="2024-12-05">
  ### Released .NET SDK v2.1.0

  Released [`v2.1.0`](https://github.com/pinecone-io/pinecone-dotnet-client/releases/tag/2.1.0) of the [Pinecone .NET SDK](https://github.com/pinecone-io/pinecone-dotnet-client). This version adds support for [index tags](/guides/manage-data/manage-indexes#configure-index-tags) and introduces the `ClientOptions.IsTlsEnabled` property, which must be set to `false` for non-secure client connections.
</Update>

<Update label="2024-12-05">
  ### Improved batch deletion guidance

  Improved the guidance and example code for [deleting records in batches](/guides/manage-data/delete-data#delete-records-in-batches).
</Update>

<Update label="2024-12-02">
  ### Launch week: Released `pinecone-sparse-english-v0`

  Pinecone Inference now supports [`pinecone-sparse-english-v0`](/guides/search/rerank-results#pinecone-sparse-english-v0), Pinecone's sparse embedding model, which estimates the lexical importance of tokens by leveraging their context, unlike traditional retrieval models like BM25, which rely solely on term frequency. This model is in [public preview](/release-notes/feature-availability).
</Update>

## November 2024

<Update label="2024-11-30">
  ### Pinecone docs: New workflows and best practices

  Added typical [Pinecone Database and Pinecone Assistant workflows](/guides/get-started/overview) to the Docs landing page.

  ***

  Updated various examples to use the production best practice of [targeting an index by host](/guides/manage-data/target-an-index) instead of name.

  ***

  Updated the [Amazon Bedrock integration setup guide](/integrations/amazon-bedrock#setup-guide). It now utilizes Bedrock Agents.
</Update>

<Update label="2024-11-27">
  ### Released Java SDK v3.1.0

  Released [`v3.1.0`](https://github.com/pinecone-io/pinecone-java-client/releases/tag/v3.1.0) of the [Pinecone Java SDK](/reference/sdks/java/overview). This version introduces support for specifying a base URL for control and data plane operations.
</Update>

<Update label="2024-11-25">
  ### Pinecone Assistant: Context snippets and structured data files

  You can now [retrieve the context snippets](/guides/assistant/retrieve-context-snippets) that Pinecone Assistant uses to generate its responses. This data includes relevant chunks, relevancy scores, and references.

  ***

  You can now [upload JSON (.json) and Markdown (.md) files](/guides/assistant/manage-files#upload-a-local-file) to an assistant.
</Update>

<Update label="2024-11-14">
  ### Monthly spend alerts

  You can now set an organization-wide [monthly spend alert](/guides/manage-cost/manage-cost#set-a-monthly-spend-alert). When your organization's spending reaches the specified limit, you will receive an email notification.
</Update>

<Update label="2024-11-14">
  ### Released .NET SDK v2.0.0

  Released [`v2.0.0`](https://github.com/pinecone-io/pinecone-dotnet-client/releases/tag/2.0.0) of the [Pinecone .NET SDK](https://github.com/pinecone-io/pinecone-dotnet-client). This version uses the latest stable API version, `2024-10`, and adds support for [embedding](/reference/api/2025-01/inference/generate-embeddings), [reranking](https://docs.pinecone.io/reference/api/2025-01/inference/rerank), and [import](/guides/index-data/import-data). It also adds support for using the .NET SDK with [proxies](https://github.com/pinecone-io/pinecone-dotnet-client#configuring-http-proxy-for-both-control-and-data-plane-operations).
</Update>

<Update label="2024-11-13">
  ### Released Python SDK v5.4.0 and v5.4.1

  Released [`v5.4.0`](https://github.com/pinecone-io/pinecone-python-client/releases/tag/v5.4.0) and [`v5.4.1`](https://github.com/pinecone-io/pinecone-python-client/releases/tag/v5.4.1) of the [Pinecone Python SDK](/reference/sdks/python/overview). `v5.4.0` adds a `query_namespaces` utility method to [run a query in parallel across multiple namespaces](/reference/sdks/python/overview#query-across-namespaces) in an index and then merge the result sets into a single ranked result set with the `top_k` most relevant results. `v5.4.1` adds support for the `pinecone-plugin-inference` package required for some [integrated inference](/reference/api/introduction#inference) operations.
</Update>

<Update label="2024-11-08">
  ### Enabled CSV export of usage and costs

  You can now download a CSV export of your organization's usage and costs from the [Pinecone console](https://app.pinecone.io/organizations/-/settings/usage).
</Update>

<Update label="2024-11-07">
  ### Added Support chat in the console

  You can now chat with the Pinecone support bot and submit support requests directly from the [Pinecone console](https://app.pinecone.io/organizations/-/settings/support).
</Update>

<Update label="2024-11-05">
  ### Published Assistant quickstart guide

  Added an [Assistant quickstart](/guides/assistant/quickstart/sdk-quickstart).
</Update>

## October 2024

<Update label="2024-10-31">
  ### Cequence released updated Scala SDK

  [Cequence](https://github.com/cequence-io) released a new version of their community-supported [Scala SDK](https://github.com/cequence-io/pinecone-scala) for Pinecone. See their [blog post](https://cequence.io/blog/industry-know-how/introducing-the-pinecone-scala-client-async-intuitive-and-ready-for-action) for details.
</Update>

<Update label="2024-10-28">
  ### Added index tagging for categorization

  You can now [add index tags](/guides/manage-data/manage-indexes#configure-index-tags) to categorize and identify indexes.
</Update>

<Update label="2024-10-24">
  ### Released major SDK updates: Node.js, Go, Java, and Python

  Released [`v4.0.0`](https://github.com/pinecone-io/pinecone-ts-client/releases/tag/v4.0.0) of the [Pinecone Node.js SDK](/reference/sdks/node/overview). This version uses the latest stable API version, `2024-10`, and adds support for [reranking](/guides/search/rerank-results) and [import](/guides/index-data/import-data).

  ***

  Released [`v2.0.0`](https://github.com/pinecone-io/go-pinecone/releases/tag/v2.0.0) of the [Pinecone Go SDK](/reference/sdks/go/overview). This version uses the latest stable API version, `2024-10`, and adds support for [reranking](/guides/search/rerank-results) and [import](/guides/index-data/import-data).

  ***

  Released [`v3.0.0`](https://github.com/pinecone-io/pinecone-java-client/releases/tag/v3.0.0) of the [Pinecone Java SDK](/reference/sdks/java/overview). This version uses the latest stable API version, `2024-10`, and adds support for [embedding](/reference/api/2025-01/inference/generate-embeddings), [reranking](/reference/api/2025-01/inference/rerank), and [import](/guides/index-data/import-data).

  <Warning>
    `v3.0.0` also includes the following [breaking change](/reference/api/versioning#breaking-changes): The `control` class has been renamed `db_control`. Before upgrading to this version, be sure to update all relevant `import` statements to account for this change.

    For example, you would change `import org.openapitools.control.client.model.*;` to `import org.openapitools.db_control.client.model.*;`.
  </Warning>

  ***

  `v5.3.0` and `v5.3.1` of the [Pinecone Python SDK](/reference/sdks/python/overview) use the latest stable API version, `2024-10`. These versions were release previously.
</Update>

<Update label="2024-10-24">
  ### Pinecone API version `2024-10` is now the latest stable version

  `2024-10` is now the latest [stable version](/reference/api/versioning#release-schedule) of the [Database API](/reference/api/2024-10/data-plane/) and [Inference API](/reference/api/2024-10/inference/). For highlights, see [SDKs](#sdks) below.
</Update>

<Update label="2024-10-17">
  ### Pinecone Inference now available on the free Starter plan

  The free [Starter plan](https://www.pinecone.io/pricing/) now supports [reranking documents with Pinecone Inference](/guides/search/rerank-results).
</Update>

<Update label="2024-10-17">
  ### Customer-managed encryption keys (CMEK) in early access

  You can now use [customer-managed encryption keys (CMEK)](/guides/production/configure-cmek) to secure indexes within a Pinecone project. This feature is in [early access](/release-notes/feature-availability).
</Update>

<Update label="2024-10-07">
  ### Serverless index monitoring generally available

  Monitoring serverless indexes with [Prometheus](/guides/production/monitoring#monitor-with-prometheus) or [Datadog](/integrations/datadog) is now in [general availability](/release-notes/feature-availability).
</Update>

<Update label="2024-10-03">
  ### Data import from Amazon S3 in public preview

  You can now [import data](/guides/index-data/import-data) into an index from [Amazon S3](/guides/operations/integrations/integrate-with-amazon-s3). This feature is in [public preview](/release-notes/feature-availability).
</Update>

<Update label="2024-10-02">
  ### Chat and update features added to Assistant

  Added the [`chat_assistant`](/reference/api/2025-01/assistant/chat_assistant) endpoint to the Assistant API. It can be used to chat with your assistant, and get responses and citations back in a structured form.

  ***

  You can now add instructions when [creating](/guides/assistant/create-assistant) or [updating](/guides/assistant/manage-assistants#update-an-existing-assistant) an assistant. Instructions are a short description or directive for the assistant to apply to all of its responses. For example, you can update the instructions to reflect the assistant's role or purpose.

  ***

  You can now [update an existing assistant](/guides/assistant/manage-assistants#update-an-existing-assistant) with new instructions or metadata.
</Update>

## September 2024

<Update label="2024-09-25">
  Added the [Matillion](/integrations/matillion) integration page.
</Update>

<Update label="2024-09-23">
  Added guidance on using the Node.js SDK with [proxies](/reference/sdks/node/overview#proxy-configuration).
</Update>

<Update label="2024-09-19">
  Released [`v5.3.1`](https://github.com/pinecone-io/pinecone-python-client/releases/tag/v5.3.1) of the [Pinecone Python SDK](/reference/sdks/python/overview). This version adds a missing `python-dateutil` dependency.

  ***

  Released [`v1.1.1`](https://github.com/pinecone-io/go-pinecone/releases/tag/v1.1.1) of the [Pinecone Go SDK](/reference/sdks/go/overview). This version adds support for non-secure client connections.

  ***

  Released [`v2.1.0`](https://github.com/pinecone-io/pinecone-java-client/releases/tag/v2.1.0) of the [Pinecone Java SDK](/reference/sdks/java/overview). This version adds support for non-secure client connections.
</Update>

<Update label="2024-09-18">
  Released [`v5.3.0`](https://github.com/pinecone-io/pinecone-python-client/releases/tag/v5.3.0) of the [Pinecone Python SDK](/reference/sdks/python/overview). This version adds support for [import](/guides/index-data/import-data) operations. This feature is in [public preview](/release-notes/feature-availability).
</Update>

<Update label="2024-09-18">
  Added the `metrics_alignment` operation, which provides a way to [evaluate the correctness and completeness of a response](/guides/assistant/evaluate-answers) from a RAG system. This feature is in [public preview](/release-notes/feature-availability).

  ***

  When using Pinecone Assistant, you can now [choose an LLM](/guides/assistant/chat-with-assistant#choose-a-model-for-your-assistant) for the assistant to use and [filter the assistant's responses by metadata](/guides/assistant/chat-with-assistant#filter-chat-with-metadata).
</Update>

<Update label="2024-09-18">
  Added the [Datavolo](/integrations/datavolo) integration pages.
</Update>

<Update label="2024-09-17">
  Released [`v5.2.0`](https://github.com/pinecone-io/pinecone-python-client/releases/tag/v5.2.0) of the [Pinecone Python SDK](/reference/sdks/python/overview). This version adds support for [reranking documents with Pinecone Inference](/guides/search/rerank-results); it is no longer necessary to install the `pinecone-plugin-inference` package separately. This feature is in [public preview](/release-notes/feature-availability).
</Update>

<Update label="2024-09-16">
  [Prometheus monitoring for serverless indexes](/guides/production/monitoring#monitor-with-prometheus) is now in [public preview](/release-notes/feature-availability).
</Update>

<Update label="2024-09-12">
  Released [`v3.0.3`](https://github.com/pinecone-io/pinecone-ts-client/releases/tag/3.0.3) of the [Pinecone Node.js SDK](/reference/sdks/node/overview). This version removes extra logging and makes general internal enhancements.
</Update>

<Update label="2024-09-11">
  If you are upgrading from the [Starter plan](https://www.pinecone.io/pricing/), you can now connect your Pinecone organization to the [AWS Marketplace](/guides/organizations/manage-billing/upgrade-billing-plan), [Google Cloud Marketplace](/guides/organizations/manage-billing/upgrade-billing-plan), or [Microsoft Marketplace](/guides/organizations/manage-billing/upgrade-billing-plan) for billing purposes.
</Update>

<Update label="2024-09-11">
  Refreshed the navigation and overall visual interface of the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/).
</Update>

<Update label="2024-09-11">
  Added Go examples for [batch upserts](/guides/index-data/upsert-data#upsert-in-batches), [parallel upserts](/guides/index-data/upsert-data#send-upserts-in-parallel), and [deleting all records for a parent document](/guides/index-data/data-modeling#delete-chunks).
</Update>

## August 2024

<Update label="2024-08-28">
  Added the [Aryn](/integrations/aryn) integration page.
</Update>

<Update label="2024-08-28">
  Released [`v3.0.2`](https://github.com/pinecone-io/pinecone-ts-client/releases/tag/3.0.2) of the [Pinecone Node.js SDK](/reference/sdks/node/overview). This version removes a native Node utility function that was causing issues for users running in `Edge`. There are no downstream affects of its removal; existing code should not be impacted.
</Update>

<Update label="2024-08-27">
  Released [`v5.1.0`](https://github.com/pinecone-io/pinecone-python-client/releases/tag/v5.1.0) of the [Pinecone Python SDK](/reference/sdks/python/overview). With this version, the SDK can now be installed with `pip install pinecone` / `pip install "pinecone[grpc]"`. This version also includes a `has_index()` helper function to check if an index exists.

  ***

  Released [`v0.1.0`](https://github.com/pinecone-io/pinecone-rust-client/releases/tag/v0.1.0) and [`v0.1.1`](https://github.com/pinecone-io/pinecone-rust-client/releases/tag/v0.1.1) of the [Pinecone Rust SDK](https://github.com/pinecone-io/pinecone-rust-client). The Rust SDK is in "alpha" and is under active development. The SDK should be considered unstable and should not be used in production. Before a 1.0 release, there are no guarantees of backward compatibility between minor versions. See the [Rust SDK README](https://github.com/pinecone-io/pinecone-rust-client) for full installation instructions and usage examples.
</Update>

<Update label="2024-08-27">
  Released [`v1.0.0`](https://github.com/pinecone-io/pinecone-dotnet-client/releases/tag/1.0.0) of the [Pinecone .NET SDK](https://github.com/pinecone-io/pinecone-dotnet-client). For usage examples, see [our guides](/guides/get-started/quickstart) or the [GitHub README](https://github.com/pinecone-io/pinecone-dotnet-client).
</Update>

<Update label="2024-08-26">
  You can now [back up](/guides/manage-data/back-up-an-index) and [restore](/guides/manage-data/restore-an-index) serverless indexes. This feature is in public preview.

  ***

  Serverless indexes are now in [general availability on GCP and Azure](/guides/index-data/create-an-index#cloud-regions) for Standard and Enterprise plans.

  ***

  You can now deploy [serverless indexes](/guides/index-data/indexing-overview) in the `europe-west1` (Netherlands) region of GCP.
</Update>

<Update label="2024-08-26">
  Released [`v1.1.0`](https://github.com/pinecone-io/go-pinecone/releases/tag/v1.1.0) of the [Pinecone Go SDK](/reference/sdks/go/overview). This version adds support for generating embeddings via [Pinecone Inference](/reference/api/introduction#inference).
</Update>

<Update label="2024-08-21">
  Added the [Nexla](/integrations/nexla) integration page.
</Update>

<Update label="2024-08-15">
  [Pinecone Assistant](/guides/assistant/overview) is now in [public preview](/release-notes/feature-availability).
</Update>

<Update label="2024-08-13">
  The Pinecone Inference API now supports [reranking](https://docs.pinecone.io/guides/search/rerank-results). This feature is in [public preview](/release-notes/feature-availability).
</Update>

<Update label="2024-08-06">
  Released [`v1.0.0`](https://github.com/pinecone-io/go-pinecone/releases/tag/v1.0.0) of the [Pinecone Go SDK](/reference/sdks/go/overview). This version depends on Pinecone API version `2024-07` and includes the ability to [prevent accidental index deletion](/guides/manage-data/manage-indexes#configure-deletion-protection). With this version, the Go SDK is [officially supported](/troubleshooting/pinecone-support-slas) by Pinecone.
</Update>

<Update label="2024-08-05">
  Added the [Nuclia](/integrations/nuclia) integration page
</Update>

## July 2024

<Update label="2024-07-30">
  Added the [Redpanda](/integrations/redpanda) integration page.
</Update>

<Update label="2024-07-26">
  Updated the [Build a RAG chatbot](/guides/get-started/build-a-rag-chatbot) guide to use Pinecone Inference for generating embeddings.
</Update>

<Update label="2024-07-19">
  Added the ability to [prevent accidental index deletion](/guides/manage-data/manage-indexes#configure-deletion-protection).
</Update>

<Update label="2024-07-19">
  Released [`v5.0.0`](https://github.com/pinecone-io/pinecone-python-client/releases/tag/v5.0.0) of the [Pinecone Python SDK](/reference/sdks/python/overview). This version depends on Pinecone API version `2024-07` and includes the ability to [prevent accidental index deletion](/guides/manage-data/manage-indexes#configure-deletion-protection). Additionally, the `pinecone-plugin-inference` package required to [generate embeddings with Pinecone Inference](/reference/api/2025-01/inference/generate-embeddings) is now included by default; it is no longer necessary to install the plugin separately.

  ***

  Released [`v3.0.0`](https://github.com/pinecone-io/pinecone-ts-client/releases/tag/v3.0.0) of the [Pinecone Node.js SDK](/reference/sdks/node/overview). This version depends on Pinecone API version `2024-07` and includes the ability to [prevent accidental index deletion](/guides/manage-data/manage-indexes#configure-deletion-protection). Additionally, this version supports generating embeddings via [Pinecone Inference](/reference/api/2025-01/inference/generate-embeddings).

  ***

  Released [`v2.0.0`](https://github.com/pinecone-io/pinecone-java-client/releases/tag/v2.0.0) of the [Pinecone Java SDK](/reference/sdks/java/overview). This version depends on Pinecone API version `2024-07` and includes the ability to [prevent accidental index deletion](/guides/manage-data/manage-indexes#configure-deletion-protection). Additionally, this version includes the following **breaking changes**:

  * `createServerlessIndex()` now requires a new argument: `DeletionProtection.ENABLED` or `DeletionProtection.DISABLED`.
  * `configureIndex()` has been renamed `configurePodsIndex()`.

  For more details, see the [Java SDK v2.0.0 migration guide](https://github.com/pinecone-io/pinecone-java-client/blob/main/v2-migration.md).
</Update>

<Update label="2024-07-19">
  Released version `2024-07` of the [Database API](/reference/api/2024-07/data-plane/) and Inference API. This version includes the following highlights:

  * The [`create_index`](/reference/api/2024-07/control-plane/create_index) and [`configure_index`](/reference/api/2024-07/control-plane/configure_index) endpoints now support the `deletion_protection` parameter. Setting this parameter to `"enabled"` prevents an index from accidental deletion. For more details, see [Prevent index deletion](/guides/manage-data/manage-indexes#configure-deletion-protection).

  * The [`describe_index`](/reference/api/2024-07/control-plane/describe_index) and [`list_index`](/reference/api/2024-07/control-plane/list_indexes) responses now include the `deletion_protection` field. This field indicates whether deletion protection is enabled for an index.

  * The `spec.serverless.cloud` and `spec.serverless.region` parameters of [`create_index`](/reference/api/2024-07/control-plane/create_index) now support `gcp` / `us-central` and `azure` / `eastus2` as part of the serverless public preview on GCP and Azure.
</Update>

<Update label="2024-07-17">
  Serverless indexes are now in [public preview on Azure](/guides/index-data/create-an-index#cloud-regions) for Standard and Enterprise plans.
</Update>

<Update label="2024-07-10">
  Released [version 1.1.0](https://github.com/pinecone-io/spark-pinecone/releases/tag/v1.1.0) of the official Spark connector for Pinecone. In this release, you can now set a [source tag](/integrations/build-integration/attribute-usage-to-your-integration). Additionally, you can now [upsert records](/guides/index-data/upsert-data) with 40KB of metadata, increased from 5KB.
</Update>

<Update label="2024-07-01">
  Serverless indexes are now in [public preview on GCP](/guides/index-data/create-an-index#cloud-regions) for Standard and Enterprise plans.
</Update>

<Update label="2024-07-01">
  Added an introduction to [key concepts in Pinecone](/guides/get-started/concepts) and how they relate to each other.

  ***

  Added the [Twelve Labs](/integrations/twelve-labs) integration page.
</Update>

## June 2024

<Update label="2024-06-30">
  Added a [model gallery](/models/overview) with details and guidance on popular embedding and reranking models, including models hosted on Pinecone's infrastructure.
</Update>

<Update label="2024-06-28">
  Released [version 1.2.2](https://github.com/pinecone-io/pinecone-java-client/releases/tag/v1.2.2) of the Pinecone Java SDK. This release simplifies the proxy configuration process. It also fixes an issue where the user agent string was not correctly setup for gRPC calls. Now, if the source tag is set by the user, it is appended to the custom user agent string.
</Update>

<Update label="2024-06-27">
  You can now load a [sample dataset](/guides/data/use-sample-datasets) into a new project.

  ***

  Simplified the process for [migrating paid pod indexes to serverless](/guides/indexes/pods/migrate-a-pod-based-index-to-serverless).
</Update>

<Update label="2024-06-25">
  The [Assistant API](/guides/assistant/overview) is now in beta release.
</Update>

<Update label="2024-06-20">
  The [Inference API](/reference/api/introduction#inference) is now in public preview.
</Update>

<Update label="2024-06-18">
  Added a new [legal semantic search](https://docs.pinecone.io/examples/sample-apps/legal-semantic-search) sample app that demonstrates low-latency natural language search over a knowledge base of legal documents.
</Update>

<Update label="2024-06-17">
  Added the [Instill](/integrations/instill) integration page.
</Update>

<Update label="2024-06-07">
  Added the [Langtrace](/integrations/langtrace) integration page.
</Update>

<Update label="2024-06-06">
  Updated Python code samples to use the gRPC version of the [Python SDK](/reference/sdks/python/overview), which is more performant than the Python SDK that interacts with Pinecone via HTTP requests.
</Update>

<Update label="2024-06-06">
  Released [version 4.1.1](https://github.com/pinecone-io/pinecone-python-client/releases/tag/v4.1.1) of the Pinecone Python SDK. In this release, you can now use colons inside source tags. Additionally, the gRPC version of the Python SDK now allows retries of up to `MAX_MSG_SIZE`.
</Update>

<Update label="2024-06-05">
  The Enterprise [quota for namespaces per serverless index](/reference/api/database-limits#namespaces-per-serverless-index) has increased from 50,000 to 100,000.
</Update>

<Update label="2024-06-04">
  Added the [Fleak](/integrations/fleak) integration page.
</Update>

## May 2024

<Update label="2024-05-31">
  Released [version 1.2.1](https://github.com/pinecone-io/pinecone-java-client/releases/tag/v1.2.1) of the [Pinecone Java SDK](/reference/sdks/java/overview). This version fixes the error `Could Not Find NameResolverProvider` using uber jar.
</Update>

<Update label="2024-05-31">
  Added the [Gathr](/integrations/gathr) integration page.
</Update>

<Update label="2024-05-30">
  Released [version 1.1.0](https://github.com/pinecone-io/pinecone-java-client/releases/tag/v1.1.0) of the [Pinecone Java SDK](/reference/sdks/java/overview). This version adds the ability to [list record IDs with a common prefix](/guides/manage-data/list-record-ids#list-the-ids-of-records-with-a-common-prefix).
</Update>

<Update label="2024-05-29">
  Released version [1.2.0](https://github.com/pinecone-io/pinecone-java-client/releases/tag/v1.2.0) of the [Pinecone Java SDK](/reference/sdks/java/overview). This version adds the ability to [list all record IDs in a namespace](/guides/manage-data/list-record-ids#list-the-ids-of-all-records-in-a-namespace).
</Update>

<Update label="2024-05-29">
  Added the following integration pages:

  * [Apify](/integrations/apify)
  * [Context Data](/integrations/context-data)
  * [Estuary](/integrations/estuary)
  * [GitHub Copilot](/integrations/github-copilot)
  * [Jina](/integrations/jina)
  * [FlowiseAI](/integrations/flowise)
  * [OctoAI](/integrations/octoai)
  * [Streamnative](/integrations/streamnative)
  * [Traceloop](/integrations/traceloop)
  * [Unstructured](/integrations/unstructured)
  * [VoyageAI](/integrations/voyage)
</Update>

<Update label="2024-05-21">
  You can now use the `ConnectPopup` function to bypass the [**Connect** widget](/integrations/build-integration/connect-your-users-to-pinecone) and open the "Connect to Pinecone" flow in a popup. This can be used in an app or website for a seamless Pinecone signup and login process.
</Update>

<Update label="2024-05-16">
  Released [version 1.0.0](https://github.com/pinecone-io/spark-pinecone/releases/tag/v1.0.0) of the official Spark connector for Pinecone. In this release, you can now upsert records into [serverless indexes](/guides/index-data/indexing-overview).
</Update>

<Update label="2024-05-08">
  Pinecone now supports [AWS PrivateLink](/guides/production/configure-private-endpoints). Create and use [Private Endpoints](/guides/production/configure-private-endpoints#manage-private-endpoints) to connect AWS PrivateLink to Pinecone while keeping your VPC private from the public internet.
</Update>

<Update label="2024-05-01">
  Released [version 4.0.0](https://github.com/pinecone-io/pinecone-python-client/releases/tag/v4.0.0) of the Pinecone Python SDK. In this release, we are upgrading the `protobuf` dependency in our optional `grpc` extras from `3.20.3` to `4.25.3`. Significant performance improvements have been made with this update. This is a breaking change for users of the optional GRPC addon ([installed with `pinecone[grpc]`](https://github.com/pinecone-io/pinecone-python-client?tab=readme-ov-file#working-with-grpc-for-improved-performance)).
</Update>

## April 2024

<Update label="2024-04-30">
  * The docs now have a new AI chatbot. Use the search bar at the top of our docs to find related content across all of our resources.
  * We've updated the look and feel of our [example notebooks](/examples/notebooks) and [sample apps](/examples/sample-apps). A new sample app, [Namespace Notes](/examples/sample-apps/namespace-notes), a simple multi-tenant RAG app that uploads documents, has also been added.
</Update>

<Update label="2024-04-30">
  The free [Starter plan](https://www.pinecone.io/pricing/) now includes 1 project, 5 serverless indexes in the `us-east-1` region of AWS, and up to 2 GB of storage. Although the Starter plan has stricter [limits](/reference/api/database-limits) than other plans, you can [upgrade](/guides/organizations/manage-billing/upgrade-billing-plan) whenever you're ready.
</Update>

<Update label="2024-04-26">
  Pinecone now provides a [**Connect** widget](/integrations/build-integration/connect-your-users-to-pinecone) that can be embedded into an app, website, or Colab notebook for a seamless signup and login process.
</Update>

<Update label="2024-04-22">
  Added the [lifecycle policy of the Pinecone API](/release-notes/feature-availability), which describes the availability phases applicable to APIs, features, and SDK versions.
</Update>

<Update label="2024-04-22">
  As announced in January 2024, [control plane](/reference/api/2024-07/control-plane) operations like `create_index`, `describe_index`, and `list_indexes` now use a single global URL, `https://api.pinecone.io`, regardless of the cloud environment where an index is hosted. This is now in general availability. As a result, the legacy version of the API, which required regional URLs for control plane operations, is deprecated as of April 15, 2024 and will be removed in a future, to be announced, release.
</Update>

<Update label="2024-04-15">
  Added the [Terraform](/integrations/terraform) integration page.
</Update>

<Update label="2024-04-15">
  Released version 0.9.0 of the [Canopy SDK](https://github.com/pinecone-io/canopy/blob/main/README.md). This version adds support for OctoAI LLM and embeddings, and Qdrant as a supported knowledge base. See the [v0.9.0 release notes](https://github.com/pinecone-io/canopy/releases/tag/v0.9.0) in GitHub for more details.
</Update>

<Update label="2024-04-12">
  You can now deploy [serverless indexes](/guides/index-data/indexing-overview) in the `eu-west-1` region of AWS.
</Update>

<Update label="2024-04-12">
  Released version 1.0.0 of the [Pinecone Java SDK](/reference/sdks/java/overview). With this version, the Java SDK is [officially supported](/troubleshooting/pinecone-support-slas) by Pinecone. For full details on the release, see the [v1.0.0 release notes](https://github.com/pinecone-io/pinecone-java-client/releases/tag/v1.0.0) in GitHub. For usage examples, see [our guides](/guides/get-started/quickstart) or the [GitHub README](https://github.com/pinecone-io/pinecone-java-client). To migrate to v1.0.0 from version 0.8.x or below, see the [Java v1.0.0 migration guide](https://github.com/pinecone-io/pinecone-java-client/blob/main/v1-migration.md).
</Update>

## March 2024

<Update label="2024-03-31">
  Added a [Troubleshooting](https://docs.pinecone.io/troubleshooting/) section, which includes content on best practices, troubleshooting, and how to address common errors.

  ***

  Added an explanation of the [Pinecone serverless architecture](/guides/get-started/database-architecture), including descriptions of the high-level components and explanations of the distinct paths for writes and reads.

  ***

  Added [considerations for querying serverless indexes with metadata filters](/guides/index-data/indexing-overview#metadata#considerations-for-serverless-indexes).
</Update>

<Update label="2024-03-30">
  Released [version 3.2.2](https://github.com/pinecone-io/pinecone-python-client/releases/tag/v3.2) of the [Pinecone Python SDK](/reference/sdks/python/overview). This version fixes a minor issue introduced in v3.2.0 that resulted in a `DeprecationWarning` being incorrectly shown to users who are not passing in the deprecated `openapi_config` property. This warning can safely be ignored by anyone who is not preparing to upgrade.
</Update>

<Update label="2024-03-29">
  Released [version 3.2.0](https://github.com/pinecone-io/pinecone-python-client/releases/tag/v3.2.0) of the [Pinecone Python SDK](/reference/sdks/python/overview). This version adds four optional configuration properties that enable the use of Pinecone [via proxy](/reference/sdks/python/overview#proxy-configuration).
</Update>

<Update label="2024-03-28">
  Released [version 2.2.0](https://github.com/pinecone-io/pinecone-ts-client/releases/tag/v2.2.0) of the [Pinecone Node.js SDK](/reference/sdks/node/overview). This releases adds an optional `sourceTag` that you can set when constructing a Pinecone client to help Pinecone associate API activity to the specified source.
</Update>

<Update label="2024-03-27">
  Released version 0.4.1 of the [Pinecone Go SDK](/reference/sdks/go/overview). This version adds an optional `SourceTag` that you can set when constructing a Pinecone client to help Pinecone associate API activity to the specified source.

  ***

  Released version 2.2.0 of the [Pinecone Node.js SDK](/reference/sdks/node/overview).

  ***

  Released [version 0.4.1](https://github.com/pinecone-io/go-pinecone/releases/tag/v0.4.1) of the [Pinecone Go SDK](/reference/sdks/go/overview).
</Update>

<Update label="2024-03-25">
  Released version 3.2.1 of the [Pinecone Python SDK](/reference/sdks/python/overview). This version adds an optional `source_tag` that you can set when constructing a Pinecone client to help Pinecone associate API activity to the specified source. See the [v3.2.1 release notes](https://github.com/pinecone-io/pinecone-python-client/releases/tag/v3.2.1) in GitHub for more details.
</Update>

<Update label="2024-03-21">
  Released version 0.8.1 of the [Canopy SDK](https://github.com/pinecone-io/canopy/blob/main/README.md). This version includes bug fixes, the removal of an unused field for Cohere chat calls, and added guidance on creating a knowledge base with a specified record encoder when using the core library. See the [v0.8.1 release notes](https://github.com/pinecone-io/canopy/releases/tag/v0.8.1) in GitHub for more details.
</Update>

<Update label="2024-03-20">
  The [Pinecone console](https://app.pinecone.io) has a new look and feel, with a brighter, minimalist design; reorganized menu items for quicker, more intuitive navigation; and easy access to recently viewed indexes in the sidebar.

  ***

  When viewing the list of indexes in a project, you can now search indexes by index name; sort indexes alphabetically, by how recently they were viewed or created, or by status; and filter indexes by index type (serverless, pod-based, or starter).
</Update>

<Update label="2024-03-15">
  Released version 0.4.0 of the [Pinecone Go SDK](/reference/sdks/go/overview). This version is a comprehensive re-write and adds support for all current [Pinecone API operations](/reference/api/introduction).
</Update>

<Update label="2024-03-14">
  Fixed a bug that caused inaccurate index fullness reporting for some pod-based indexes on GCP.

  ***

  You can now deploy [serverless indexes](/guides/index-data/indexing-overview) in the `us-east-1` region of AWS.
</Update>

<Update label="2024-03-06">
  Released version 2.1.0 of the [Pinecone Node.js SDK](/reference/sdks/node/overview). This version adds support for [listing the IDs of records in a serverless index](/guides/manage-data/list-record-ids). You can list all records or just those with a common ID prefix.
</Update>

<Update label="2024-03-05">
  You can now [configure single single-on](/guides/production/configure-single-sign-on/okta) to manage your teams' access to Pinecone through any identity management solution with SAML 2.0 support, such as Okta. This feature is available on the [Enterprise plan](https://www.pinecone.io/pricing/) only.
</Update>

## February 2024

<Update label="2024-02-29">
  Updated the [Langchain integration guide](/integrations/langchain) to avoid a [namespace collision issue](/troubleshooting/pinecone-attribute-errors-with-langchain).
</Update>

<Update label="2024-02-27">
  The latest version of the [Canopy SDK](https://github.com/pinecone-io/canopy/blob/main/README.md) (v0.8.0) adds support for Pydantic v2. For applications depending on Pydantic v1, this is a breaking change; review the [Pydantic v1 to v2 migration guide](https://docs.pydantic.dev/latest/migration/) and make the necessary changes before upgrading. See the [Canopy SDK release notes](https://github.com/pinecone-io/canopy/releases/tag/v0.8.0) in GitHub for more details.
</Update>

<Update label="2024-02-23" description="SDK">
  The latest version of Pinecone's Python SDK (v3.1.0) adds support for [listing the IDs of records in a serverless index](/guides/manage-data/list-record-ids). You can list all records or just those with a [common ID prefix](/guides/index-data/data-modeling#use-structured-ids). See the [Python SDK release notes](https://github.com/pinecone-io/pinecone-python-client/releases/tag/v3.1.0) in GitHub for more details.
</Update>

<Update label="2024-02-22">
  Improved the docs for [setting up billing through the AWS Marketplace](/guides/organizations/manage-billing/upgrade-billing-plan) and [Google Cloud Marketplace](/guides/organizations/manage-billing/upgrade-billing-plan).
</Update>

<Update label="2024-02-16">
  It is now possible to convert a pod-based starter index to a serverless index. For organizations on the Starter plan, this requires upgrading to Standard or Enterprise; however, upgrading comes with \$100 in serverless credits, which will cover the cost of a converted index for some time.
</Update>

<Update label="2024-02-01">
  Added a [Llamaindex integration guide](/integrations/llamaindex) on building a RAG pipeline with LlamaIndex and Pinecone.
</Update>

## January 2024

<Update label="2024-01-31">
  The latest version of the [Canopy SDK](https://github.com/pinecone-io/canopy/blob/main/README.md) (v0.6.0) adds support for the new API mentioned above as well as namespaces, LLMs that do not have function calling functionality for query generation, and more. See the [release notes](https://github.com/pinecone-io/canopy/releases/tag/v0.6.0) in GitHub for more details.
</Update>

<Update label="2024-01-09">
  The latest versions of Pinecone's Python SDK (v3.0.0) and Node.js SDK (v2.0.0) support the new API. To use the new API, existing users must upgrade to the new client versions and adapt some code. For guidance, see the [Python SDK v3 migration guide](https://canyon-quilt-082.notion.site/Pinecone-Python-SDK-v3-0-0-Migration-Guide-056d3897d7634bf7be399676a4757c7b) and [Node.js SDK v2 migration guide](https://github.com/pinecone-io/pinecone-ts-client/blob/main/v2-migration.md).
</Update>

<Update label="2024-01-09">
  The Pinecone documentation is now versioned. The default "latest" version reflects the new Pinecone API. The "legacy" version reflects the previous API, which requires regional URLs for control plane operations and does not support serverless indexes.
</Update>

<Update label="2024-01-09">
  The [new Pinecone API](/reference/api) gives you the same great vector database but with a drastically improved developer experience. The most significant improvements include:

  * [Serverless indexes](/guides/index-data/indexing-overview): With serverless indexes, you don't configure or manage compute and storage resources. You just load your data and your indexes scale automatically based on usage. Likewise, you don't pay for dedicated resources that may sometimes lay idle. Instead, the pricing model for serverless indexes is consumption-based: You pay only for the amount of data stored and operations performed, with no minimums.

  * [Multi-region projects](/guides/projects/understanding-projects): Instead of choosing a cloud region for an entire project, you now [choose a region for each index](/guides/index-data/create-an-index#create-a-serverless-index) in a project. This makes it possible to consolidate related indexes in the same project, even when they are hosted in different regions.

  * [Global URL for control plane operations](/reference): Control plane operations like `create_index`, `describe_index`, and `list_indexes` now use a single global URL, `https://api.pinecone.io`, regardless of the cloud environment where an index is hosted. This simplifies the experience compared to the legacy API, where each environment has a unique URL.
</Update>


# 2025 releases
Source: https://docs.pinecone.io/release-notes/2025

Pinecone release notes for 2025: new features, improvements, and API changes.

## December 2025

<Update label="2025-12-29">
  ### Increased metadata limit for assistants

  The metadata field limit for assistants has been increased from 1KB to 16KB.

  Assistant metadata is a JSON object that you can use to store custom organizational data, tags, and attributes for your assistants. You can specify metadata when creating an assistant by including a `metadata` field in your request, or update it later using the update assistant endpoint.

  For more information, see [Create an assistant](/reference/api/latest/assistant/create_assistant) and [Manage assistants](/guides/assistant/manage-assistants).
</Update>

<Update label="2025-12-23">
  ### Test Pinecone at scale

  Added a new guide to help you [test Pinecone at production scale](/guides/get-started/test-at-scale). The guide describes how to create an index, import 10 million vectors, and then use Vector Search Bench (VSB) to capture performance metrics for 100,000 queries. To run this test, consider signing up for a [Standard plan trial](/guides/organizations/manage-billing/standard-trial).
</Update>

<Update label="2025-12-22">
  ### Pinecone Assistant now supports GPT-5

  Pinecone Assistant now supports the GPT-5 model. To use it, set `model` to `gpt-5` when [chatting with your assistant](/reference/api/latest/assistant/chat_assistant).

  For more information, see [Chat with Assistant](/guides/assistant/chat-with-assistant#choose-a-model) and [Chat through the OpenAI-compatible interface](/guides/assistant/chat-through-the-openai-compatible-interface#choose-a-model).
</Update>

<Update label="2025-12-12">
  ### Upgrade from Starter to Standard trial

  Organizations on the Starter plan can now upgrade to a Standard plan trial at any time. The Standard trial provides 21 days and \$300 in credits to test Pinecone at scale, with access to Standard plan features such as higher limits. For more information, see [Standard plan trial](/guides/organizations/manage-billing/standard-trial).
</Update>

<Update label="2025-12-07">
  ### Delete Assistant files while they are still processing

  You can now delete a file uploaded to an assistant while it is still processing. Previously, you had to wait for file processing to complete before you could delete a file.

  For more information, see [Manage files](/guides/assistant/manage-files).
</Update>

<Update label="2025-12-02">
  ### Annual commit discount

  In the Pinecone console, customers on Standard and Enterprise pay-as-you-go plans can now commit to an annual contract and receive a discount on usage. For more information, see [Understanding cost](/guides/manage-cost/understanding-cost#discounts).
</Update>

<Update label="2025-12-02">
  ### Increased instructions limit for assistants

  The maximum size for assistant instructions has been increased from 8 KB to 16 KB.

  Instructions are included in every chat API call. Longer instructions increase input token costs for each request and consume more of the LLM's context window, reducing available space for retrieved context and conversation history.

  For more information, see [Create an assistant](/reference/api/latest/assistant/create_assistant) and [Manage assistants](/guides/assistant/manage-assistants).
</Update>

<Update label="2025-12-01">
  ### Dedicated Read Nodes: now in public preview

  [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) is now in [public preview](/release-notes/feature-availability). Users on Standard and Enterprise plans can now create Dedicated Read Nodes indexes using the console and API.

  With Dedicated Read Nodes, you can provision read hardware for large, high-throughput indexes that require predictable, low latency.

  For more information, see [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes).
</Update>

## November 2025

<Update label="2025-11-19">
  ### Pinecone API version `2025-10` is now the latest stable version

  `2025-10` is now the latest [stable version](/reference/api/versioning#release-schedule) of the [Pinecone APIs](/reference/api/introduction). This version does not include any breaking changes, and provides the following new features:

  **[Dedicated read nodes](/guides/index-data/dedicated-read-nodes) (early access):**

  * The [Create an index](/reference/api/2025-10/control-plane/create_index) and [Configure index](/reference/api/2025-10/control-plane/configure_index) endpoints allow you to create and configure indexes that use dedicated read nodes. With dedicated read nodes, you can allocate dedicated hardware for read operations. This is useful for large, high-QPS indexes that require consistent, predictable low latency.
  * The [Describe an index](/reference/api/2025-10/control-plane/describe_index) endpoint now allows you to view information about a dedicated index: shards, replicas, and scaling status.

  **Namespace and metadata schema management:**

  * The [Create a namespace](/reference/api/2025-10/data-plane/createnamespace) endpoint allows you to create a namespace without upserting vectors. You can optionally configure a metadata schema when creating the namespace to pre-declare which metadata fields should be indexed for filtering.
  * The [List namespaces](/reference/api/2025-10/data-plane/listnamespaces) endpoint now supports filtering namespaces by prefix and returns the total count of matching namespaces.
  * The [Describe a namespace](/reference/api/2025-10/data-plane/describenamespace) endpoint allows you to view the metadata schema configuration for a namespace, including which fields are indexed for filtering.
  * The [Create an index](/reference/api/2025-10/control-plane/create_index) endpoint now allows you to specify a metadata schema at index creation time to pre-declare which metadata fields should be indexed for filtering across all namespaces.

  **Update and fetch by metadata:**

  * The [Update a vector](/reference/api/2025-10/data-plane/update) endpoint allows you to update metadata across multiple records in a namespace using a metadata filter expression, eliminating the need to update records individually by ID.
  * The [Fetch vectors by metadata](/reference/api/2025-10/data-plane/fetch_by_metadata) endpoint allows you to fetch vectors using metadata filters without knowing their vector IDs.

  **Enhanced sparse search:**

  * The [Search with text](/reference/api/2025-10/data-plane/search_records) endpoint now supports a `match_terms` parameter that allows you to specify terms that must be present in search results for sparse indexes.
</Update>

<Update label="2025-11-03">
  ### n8n quickstarts

  Added new quickstart options to create an n8n workflow that downloads files via HTTP and lets you chat with them using Pinecone and OpenAI.

  * [n8n quickstart for Pinecone Assistant](/guides/assistant/quickstart/n8n-quickstart)
  * [n8n quickstart for Pinecone Database](/guides/get-started/quickstart#n8n)
</Update>

<Update label="2025-11-03">
  ### Released Node.js SDK v6.1.3

  Released [`v6.1.3`](https://github.com/pinecone-io/pinecone-ts-client/releases/tag/v6.1.3) of the [Pinecone Node.js SDK](/reference/sdks/node/overview).

  This version of the SDK fixes a bug in `Assistant.listFiles()`. Previously, when passing a `filter` to `listFiles`, the top-level `metadata` object was not handled correctly. This caused the method to return all files, regardless of the filter.

  It's no longer necessary to provide a top-level `metadata` object. Instead, declare metadata fields directly in the `filter` object:

  * ✅ `const files = await assistant.listFiles({ filter: { document_type: 'manuscript' } });`
  * ❌ `const files = await assistant.listFiles({ filter: { metadata: { document_type: 'manuscript' } } });`

  If you're using the old syntax, update it so that your filter works correctly. For more information about listing the files associated with an assistant, see [Manage files](/guides/assistant/manage-files).
</Update>

## October 2025

<Update label="2025-10-30">
  ### Increased files per assistant on the Starter plan

  On the Starter plan, you can now upload up to 100 files to an assistant. Previously, the limit was 10 files.

  To learn more, see [Assistant limits](/guides/assistant/pricing-and-limits#assistant-limits).
</Update>

<Update label="2025-10-23">
  ### Enhanced monthly spend alerts

  You can now set multiple spend alerts to monitor your organization's monthly spending. These alerts notify designated recipients when spending reaches specified thresholds. The alerts automatically reset at the start of each monthly billing cycle.

  Additionally, to protect from unexpected cost increases, Pinecone sends an alert when spending exceeds double your previous month's invoice amount. While the alert threshold is fixed, you can modify which email addresses receive the alert and enable or disable the alert notifications.

  To learn more, see [Manage cost](/guides/manage-cost/manage-cost).
</Update>

<Update label="2025-10-16">
  ### Agentic quickstart

  Added new [agentic quickstart](/guides/get-started/quickstart#cursor) options to help you build Pinecone applications with AI coding agents like Claude Code and Cursor. Instead of copying code snippets, you work with an agent that understands Pinecone APIs and implements production-ready patterns automatically.
</Update>

<Update label="2025-10-16">
  ### AI Engine integration

  Added the [AI Engine](/integrations/ai-engine) integration page.
</Update>

<Update label="2025-10-09">
  ### Pinecone CLI v0.1.0

  We've released [v0.1.0](https://github.com/pinecone-io/cli/releases/tag/v0.1.0) of the [Pinecone CLI](https://github.com/pinecone-io/cli). The CLI lets you manage Pinecone infrastructure (organizations, projects, indexes, and API keys) directly from your terminal and in CI/CD.

  This feature is in [public preview](/release-notes/feature-availability). We'll be adding more features to the CLI over time, and we'd love your [feedback](https://community.pinecone.io/) on this early version.

  For more information, see the [CLI quickstart](/reference/cli/quickstart).
</Update>

## September 2025

<Update label="2025-09-30">
  ### Production best practices

  Added a new [error handling guide](/guides/production/error-handling) to help you handle errors gracefully in production, including implementing retry logic with exponential backoff for rate limits and transient errors.

  Updated the [production checklist](/guides/production/production-checklist) with enhanced guidance on data modeling, database limits, and performance optimization.
</Update>

<Update label="2025-09-11">
  ### Changing payment methods

  Added a new guide to help customers [change their payment method](/guides/organizations/manage-billing/change-payment-method) for Pinecone's Standard or Enterprise plan, including switching from credit card to marketplace billing and vice versa.
</Update>

<Update label="2025-09-04">
  ### Released Pinecone Terraform Provider v2.0.0

  Released [v2.0.0](https://github.com/pinecone-io/terraform-provider-pinecone/releases/tag/v2.0.0) of the [Terraform Provider for Pinecone](/integrations/terraform). This version adds support for managing API keys and projects.
</Update>

<Update label="2025-09-02">
  ### Multimodal context for assistants

  Assistants can now gather context from images in PDF files. To learn more, see [Multimodal context for assistants](/guides/assistant/multimodal). This feature is in [public preview](/release-notes/feature-availability).
</Update>

## August 2025

<Update label="2025-08-29">
  ### Filter lexical search by required terms

  You can now filter lexical search results to require specific terms. This is especially useful for filtering out results that don't contain essential keywords, requiring domain-specific terminology in results, and ensuring specific people, places, or things are mentioned. This feature is in [public preview](/release-notes/feature-availability).

  To learn more, see [Filter by required terms](/guides/search/lexical-search#filter-by-required-terms).
</Update>

<Update label="2025-08-26">
  ### Zapier integration

  Added the [Zapier](/integrations/zapier) integration page.
</Update>

<Update label="2025-08-25">
  ### SSO setup improvements

  We've streamlined the SSO setup process, eliminating the need to add placeholder URLs to your identity provider. To learn more, see [Configure SSO with Okta](/guides/production/configure-single-sign-on/okta).
</Update>

<Update label="2025-08-25">
  ### Update metadata across multiple records

  You can now [update metadata across multiple records](/guides/manage-data/update-data#update-metadata-across-multiple-records) in a namespace. This feature is in [early access](/release-notes/feature-availability).
</Update>

<Update label="2025-08-13">
  ### Data import from Azure Blob Storage

  Now, you can import data from an Azure Blob Storage container into a Pinecone index. This feature is in [public preview](/release-notes/feature-availability).

  To learn more, read:

  * [Integrate with Azure Blob Storage](/guides/operations/integrations/integrate-with-azure-blob-storage)
  * [Import records](/guides/index-data/import-data)
  * [Pinecone's pricing](https://www.pinecone.io/pricing/)
</Update>

<Update label="2025-08-12">
  ### Assistant MCP server endpoint update

  **Breaking Change**: After August 31, 2025 at 11:59:59 PM UTC, the SSE-based MCP endpoint for assistants (`/mcp/assistants/<YOUR_ASSISTANT_NAME>/sse`) will no longer work.

  Before then, update your applications to use the streamable HTTP transport MCP endpoint (`/mcp/assistants/<YOUR_ASSISTANT_NAME>`). This endpoint follows the current [MCP protocol specification](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http) and provides improved flexibility and compatibility.

  Please note that Assistant MCP servers are in [early access](/release-notes/feature-availability) and are not intended for production usage.

  For more information, see [Use an Assistant MCP server](/guides/assistant/mcp-server).
</Update>

<Update label="2025-08-04">
  ### VoltAgent integration

  Added the [VoltAgent](/integrations/voltagent) integration page.
</Update>

## July 2025

<Update label="2025-07-28">
  ### Increased context window for `pinecone-sparse-english-v0`

  You can now raise the context window for Pinecone's hosted [`pinecone-sparse-english-v0`](/guides/index-data/create-an-index#pinecone-sparse-english-v0) embedding model from `512` to `2048` using the `max_tokens_per_sequence` parameter.
</Update>

<Update label="2025-07-23">
  ### Release Go SDK v4.1.0, v4.1.1, and v4.1.2

  Released [`v4.1.0`](https://github.com/pinecone-io/go-pinecone/releases/tag/v4.1.0), [`v4.1.1`](https://github.com/pinecone-io/go-pinecone/releases/tag/v4.1.1), and [`v4.1.2`](https://github.com/pinecone-io/go-pinecone/releases/tag/v4.1.2) of the [Pinecone Go SDK](/reference/sdks/go/overview).

  * `v4.1.0` adds support for admin API operations for working with API keys, projects, and service accounts.
  * `v4.1.1` adds `PercentComplete` and `RecordsImported` to the response when [describing an import](/guides/index-data/import-data#track-import-progress) and [listing imports](/guides/index-data/import-data#list-imports).
  * `v4.1.2` adds support for [migrating a pod-based index to serverless](/guides/indexes/pods/migrate-a-pod-based-index-to-serverless#3-start-migration).
</Update>

<Update label="2025-07-23">
  ### Release Node.js SDK v6.1.2

  Released [`v6.1.2`](https://github.com/pinecone-io/pinecone-ts-client/releases/tag/v6.1.2) of the [Pinecone Node.js SDK](/reference/sdks/node/overview). This version adds support for the following:

  * [Migrating a pod-based index to serverless](/guides/indexes/pods/migrate-a-pod-based-index-to-serverless#3-start-migration).
  * Controlling whether `signed_url` is included in the response when [describing a file](/guides/assistant/manage-files#get-the-status-of-a-file) for an assistant.
</Update>

## June 2025

<Update label="2025-06-26">
  ### Unlimited assistant file storage for paid plans

  Organizations on the [Standard and Enterprise plans](https://www.pinecone.io/pricing/) now have [unlimited file storage](/reference/api/assistant/assistant-limits) for their assistants. Previously, organizations on these plans were limited to 10 GB of file storage per project.
</Update>

<Update label="2025-06-23">
  ### Data import from Google Cloud Storage

  You can now [import data](/guides/index-data/import-data) into an index from [Google Cloud Storage](/guides/operations/integrations/integrate-with-google-cloud-storage). This feature is in [public preview](/release-notes/feature-availability).
</Update>

<Update label="2025-06-20">
  ### Released Python SDK v7.1.0, v7.2.0, and v7.3.0

  Released [`v7.1.0`](https://github.com/pinecone-io/pinecone-python-client/releases/tag/v7.1.0), [`v7.2.0`](https://github.com/pinecone-io/pinecone-python-client/releases/tag/v7.2.0), and [`v7.3.0`](https://github.com/pinecone-io/pinecone-python-client/releases/tag/v7.3.0) of the [Pinecone Python SDK](/reference/sdks/python/overview).

  * `v7.1.0` fixes minor bugs.
  * `v7.2.0` adds support for [managing namespaces](/guides/manage-data/manage-namespaces).
  * `v7.3.0` adds support for admin API operations for working with API keys, projects, and service accounts.
</Update>

<Update label="2025-06-16">
  ### Released Go SDK v4.0.0 and v4.0.1

  Released [`v4.0.0`](https://github.com/pinecone-io/go-pinecone/releases/tag/v4.0.0) and [`v4.0.1`](https://github.com/pinecone-io/go-pinecone/releases/tag/v4.0.1) of the [Pinecone Go SDK](/reference/sdks/go/overview).

  Go SDK `v4.0.0` uses the latest stable API version, `2025-04`, and includes support for the following:

  * [Managing namespaces](/guides/manage-data/manage-namespaces)
  * [Reusing an index connection with a new namespace](/guides/manage-data/target-an-index#target-by-index-host-recommended) (see the Go example)
  * [Creating and managing backups](/guides/manage-data/back-up-an-index)
  * [Restoring indexes from backups](/guides/manage-data/restore-an-index)
  * [Listing embedding and reranking models hosted by Pinecone](/reference/api/2025-04/inference/list_models)
  * [Getting details about a model hosted by Pinecone](/reference/api/2025-04/inference/describe_model)

  Go SDK `v4.0.1` expands the [`DescribeIndex`](/guides/production/configure-private-endpoints#read-and-write-data) response to include the `private_host` value for connecting to indexes with a private endpoint.
</Update>

<Update label="2025-06-16">
  ### Released Node.js SDK v6.1.1

  Released [`v6.1.1`](https://github.com/pinecone-io/pinecone-ts-client/releases/tag/v6.1.1) of the [Pinecone Node.js SDK](/reference/sdks/node/overview). This version adds support for [setting the sampling temperature](/guides/assistant/chat-with-assistant#set-the-sampling-temperature) for an assistant, and expands the [`describeIndex`](/guides/production/configure-private-endpoints#read-and-write-data) response to include the `private_host` value for connecting to indexes with a private endpoint.
</Update>

<Update label="2025-06-12">
  ### Data modeling guide

  Added a new guide to help you [model your data](/guides/index-data/data-modeling) for efficient ingestion, retrieval, and management in Pinecone.
</Update>

<Update label="2025-06-05">
  ### Released Java SDK v5.1.0

  Released [`v5.1.0`](https://github.com/pinecone-io/pinecone-java-client/releases/tag/v5.1.0) of the [Pinecone Java SDK](/reference/sdks/java/overview). This version adds support for [listing](/reference/api/2025-04/inference/list_models) and [describing](/reference/api/2025-04/inference/describe_model) embedding and reranking models hosted by Pinecone.
</Update>

<Update label="2025-06-05">
  ### Released Node.js SDK v6.1.0

  Released [`v6.1.0`](https://github.com/pinecone-io/pinecone-ts-client/releases/tag/v6.1.0) of the [Pinecone Node.js SDK](/reference/sdks/node/overview). This version adds support for [controlling the context snippets sent to the LLM](/guides/assistant/chat-with-assistant#control-the-context-snippets-sent-to-the-llm) by an assistant.
</Update>

## May 2025

<Update label="2025-05-29">
  ### Released Python SDK v7.0.1 and v7.0.2

  Released [`v7.0.1`](https://github.com/pinecone-io/pinecone-python-client/releases/tag/v7.0.1) and [`v7.0.2`](https://github.com/pinecone-io/pinecone-python-client/releases/tag/v7.0.2) of the [Pinecone Python SDK](/reference/sdks/python/overview). These versions fix minor bugs discovered since the release of the `v7.0.0` major version.
</Update>

<Update label="2025-05-29">
  ### Released Node.s SDK v6.0.1

  Released [`v6.0.1`](https://github.com/pinecone-io/pinecone-ts-client/releases/tag/v6.0.1) of the [Pinecone Node.js SDK](/reference/sdks/node/overview). This version adds pagination to the [`listBackups`](/guides/manage-data/back-up-an-index#list-backups-in-a-project) operation.
</Update>

<Update label="2025-05-19">
  ### Pinecone API version `2025-04` is now the latest stable version

  `2025-04` is now the latest [stable version](/reference/api/versioning#release-schedule) of the [Pinecone APIs](/reference/api/introduction). For highlights, see the SDK releases below.
</Update>

<Update label="2025-05-19">
  ### Released Python SDK v7.0.0

  Released [`v7.0.0`](https://github.com/pinecone-io/pinecone-python-client/releases/tag/v7.0.0) of the [Pinecone Python SDK](/reference/sdks/python/overview). This version uses the latest stable API version, `2025-04`, and includes support for the following:

  * [Creating and managing backups](/guides/manage-data/back-up-an-index)
  * [Restoring indexes from backups](/guides/manage-data/restore-an-index)
  * [Listing embedding and reranking models hosted by Pinecone](/reference/api/2025-04/inference/list_models)
  * [Getting details about a model hosted by Pinecone](/reference/api/2025-04/inference/describe_model)
  * [Creating a BYOC index](/guides/production/bring-your-own-cloud#create-an-index)

  Additionally, the `pinecone-plugin-assistant` package required to work with [Pinecone Assistant](/guides/assistant/overview) is now included by default; it is no longer necessary to install the plugin separately.
</Update>

<Update label="2025-05-19">
  ### Released Node.js SDK v6.0.0

  Released [`v6.0.0`](https://github.com/pinecone-io/pinecone-ts-client/releases/tag/v6.0.0) of the [Pinecone Node.js SDK](/reference/sdks/node/overview). This version uses the latest stable API version, `2025-04`, and includes support for the following:

  * [Managing namespaces](/guides/manage-data/manage-namespaces)
  * [Creating and managing backups](/guides/manage-data/back-up-an-index)
  * [Restoring indexes from backups](/guides/manage-data/restore-an-index)
  * [Listing embedding and reranking models hosted by Pinecone](/reference/api/2025-04/inference/list_models)
  * [Getting details about a model hosted by Pinecone](/reference/api/2025-04/inference/describe_model)
</Update>

<Update label="2025-05-19">
  ### Released Java SDK v5.0.0

  Released [`v5.0.0`](https://github.com/pinecone-io/pinecone-java-client/releases/tag/v5.0.0) of the [Pinecone Java SDK](/reference/sdks/java/overview). This version uses the latest stable API version, `2025-04`, and includes support for the following:

  * [Creating indexes with integrated embedding and reranking](/guides/index-data/indexing-overview#integrated-embedding)
  * [Upserting text to an integrated index](/guides/index-data/upsert-data)
  * [Searching an integrated index with text](/guides/search/semantic-search#search-with-text)
  * [Managing namespaces](/guides/manage-data/manage-namespaces)
  * [Creating and managing backups](/guides/manage-data/back-up-an-index)
  * [Restoring indexes from backups](/guides/manage-data/restore-an-index)
</Update>

<Update label="2025-05-19">
  ### Released .NET SDK v4.0.0

  Released [`v4.0.0`](https://github.com/pinecone-io/pinecone-dotnet-client/releases/tag/4.0.0) of the [Pinecone .NET SDK](https://github.com/pinecone-io/pinecone-dotnet-client). This version uses the latest stable API version, `2025-04`, and includes support for the following:

  * [Creating indexes with integrated embedding and reranking](/guides/index-data/indexing-overview#integrated-embedding)
  * [Upserting text to an integrated index](/guides/index-data/upsert-data)
  * [Searching an integrated index with text](/guides/search/semantic-search#search-with-text)
  * [Managing namespaces](/guides/manage-data/manage-namespaces)
  * [Creating and managing backups](/guides/manage-data/back-up-an-index)
  * [Restoring indexes from backups](/guides/manage-data/restore-an-index)
  * [Listing embedding and reranking models hosted by Pinecone](/reference/api/2025-04/inference/list_models)
  * [Getting details about a model hosted by Pinecone](/reference/api/2025-04/inference/describe_model)

  <Warning>
    Before upgrading to `v4.0.0`, update all relevant code to account for the following [breaking changes](/reference/api/versioning#breaking-changes). See the [`v4.0.0`](https://github.com/pinecone-io/pinecone-dotnet-client/releases/tag/4.0.0) release notes for full details.

    * The [`create_index`](/reference/api/2025-04/control-plane/create_index) and [`create_for_model`](/reference/api/2025-04/control-plane/create_for_model) operations:
      * `CreateIndexRequestMetric` has been renamed to `MetricType`.
    * The [`list_indexes`](/reference/api/2025-04/control-plane/list_indexes) operation:
      * `ModelIndexEmbedMetric` has been renamed to `MetricType`.
    * The [`embed`](/reference/api/2025-04/inference/generate-embeddings) operation:
      * `SparseEmbedding.SparseIndices` has changed from `IEnumerable<int>` to `IEnumerable<long>`.
  </Warning>
</Update>

<Update label="2025-05-06">
  ### New Docs IA

  We've overhauled the information architecture of our guides to mirror the goals of users, from indexing to searching to optimizing to production.

  This change includes distinct pages for search types:

  * [Semantic search](https://docs.pinecone.io/guides/search/semantic-search)
  * [Lexical search](https://docs.pinecone.io/guides/search/lexical-search)
  * [Hybrid search](https://docs.pinecone.io/guides/search/hybrid-search)

  And optimization techniques:

  * [Increase relevance](https://docs.pinecone.io/guides/optimize/increase-relevance)
  * [Increase throughput](https://docs.pinecone.io/guides/optimize/increase-throughput)
  * [Decrease latency](https://docs.pinecone.io/guides/optimize/decrease-latency)
</Update>

## April 2025

<Update label="2025-04-25">
  ### Bring Your Own Cloud (BYOC) in GCP

  The [Bring Your Own Cloud (BYOC)](/guides/production/bring-your-own-cloud) offering is now available in GCP. Organizations with high security and compliance requirements can use BYOC to deploy Pinecone Database in their own GCP account. This feature is in [public preview](/release-notes/feature-availability).
</Update>

<Update label="2025-04-21">
  ### Integrate AI agents with Pinecone MCP

  [Pinecone's open-source MCP server](/guides/operations/mcp-server) enables AI agents to interact directly with Pinecone's functionality and documentation via the standardized [Model Context Protocol (MCP)](https://modelcontextprotocol.io/l). Using the MCP server, agents can search Pinecone documentation, manage indexes, upsert data, and query indexes for relevant information.
</Update>

<Update label="2025-04-21">
  ### Add context to AI agents with Assistant MCP

  Every Pinecone Assistant now has a [dedicated MCP server](/guides/assistant/mcp-server) that gives AI agents direct access to the assistant's knowledge through the standardized [Model Context Protocol (MCP)](https://modelcontextprotocol.io/).
</Update>

<Update label="2025-04-21">
  ### Upload a file from an in-memory binary stream

  You can [upload a file to an assistant directly from an in-memory binary stream](/guides/assistant/upload-files#upload-from-a-binary-stream) using the Python SDK and the BytesIO class.
</Update>

<Update label="2025-04-21">
  ### Released Pinecone Terraform Provider v1.0.0

  Released [v1.0.0](https://github.com/pinecone-io/terraform-provider-pinecone/releases/tag/v1.0.0) of the [Terraform Provider for Pinecone](/integrations/terraform). This version adds support for [sparse indexes](/guides/index-data/indexing-overview#indexes-with-sparse-vectors), [indexes with integrated embedding and reranking](/guides/index-data/indexing-overview#integrated-embedding), [index tags](/guides/manage-data/manage-indexes#configure-index-tags), and [index deletion protection](/guides/manage-data/manage-indexes#configure-deletion-protection).
</Update>

<Update label="2025-04-13">
  ### Released .NET SDK v3.1.0

  Released [`v3.1.0`](https://github.com/pinecone-io/pinecone-dotnet-client/releases/tag/3.1.0) of the [Pinecone .NET SDK](https://github.com/pinecone-io/pinecone-dotnet-client). This version adds support for [indexes with integrated embedding and reranking](/guides/index-data/indexing-overview#integrated-embedding).
</Update>

<Update label="2025-04-04">
  ### LLM shortcuts for Pinecone docs

  You can now use the "Copy page" options at the top of every page of the Pinecone documentation to quickly ground LLMs with Pinecone-specific context.
</Update>

## March 2025

<Update label="2025-03-26">
  ### Control the context snippets the assistant sends to the LLM

  You can [control the context snippets sent to the LLM](/guides/assistant/chat-with-assistant#control-the-context-snippets-sent-to-the-llm) by setting `context_options` in the request.
</Update>

<Update label="2025-03-24">
  ### Released Go SDK v3.1.0

  Released [`v3.1.0`](https://github.com/pinecone-io/go-pinecone/releases/tag/v3.1.0) of the [Pinecone Go SDK](/reference/sdks/go/overview). This version adds support for [indexes with integrated embedding and reranking](/guides/index-data/indexing-overview#integrated-embedding).
</Update>

<Update label="2025-03-21">
  <img />

  ### Launch week: Dark mode

  Dark mode is now out for Pinecone's website, docs, and console. You can change your theme at the top right of each site.
</Update>

<Update label="2025-03-20">
  ### Launch week: Self-service audit logs

  You can now enable and [configure audit logs](/guides/production/configure-audit-logs) for your Pinecone organization. [Audit logs](/guides/production/security-overview#audit-logs) provide a detailed record of user, service account, and API actions that occur within Pinecone. This feature is in [public preview](/release-notes/feature-availability) and available only on [Enterprise plans](https://www.pinecone.io/pricing/).
</Update>

<Update label="2025-03-19">
  ### Launch week: Introducing the Admin API and service accounts

  You can now use [service accounts](/guides/organizations/understanding-organizations#service-accounts) to programmatically manage your Pinecone organization through the Admin API. Use the Admin API to [create](/guides/projects/create-a-project) and [manage projects](/guides/projects/manage-projects), as well as [create and manage API keys](/guides/projects/manage-api-keys). The Admin API and service accounts are in [public preview](/release-notes/feature-availability).
</Update>

<Update label="2025-03-18">
  ### Launch week: Back up an index through the API

  You can now [back up an index](/guides/manage-data/back-up-an-index) and [restore an index](/guides/manage-data/restore-an-index) through the Pinecone API. This feature is in [public preview](/release-notes/feature-availability).
</Update>

<Update label="2025-03-17">
  ### Launch week: Optimized database architecture

  Pinecone has optimized its [serverless database architecture](/guides/get-started/database-architecture) to meet the growing demand for large-scale agentic workloads and improved performance for search and recommendation workloads. New customers will use this architecture by default, and existing customers will gain access over the next month.
</Update>

<Update label="2025-03-13">
  ### Firebase Genkit integration

  Added the [Firebase Genkit](/integrations/genkit) integration page.
</Update>

<Update label="2025-03-10">
  ### Bring Your Own Cloud (BYOC) in public preview

  [Bring Your Own Cloud (BYOC)](/guides/production/bring-your-own-cloud) lets you deploy Pinecone Database in your private AWS account to ensure data sovereignty and compliance, with Pinecone handling provisioning, operations, and maintenance. This feature is in [public preview](/release-notes/feature-availability) on AWS.
</Update>

## February 2025

<Update label="2025-02-21">
  ### Docs site refresh

  We've refreshed the look and layout of the [Pinecone documentation](https://docs.pinecone.io) site. You can now use the dropdown at the top of the side navigation to view documentation for either [Pinecone Database](/guides/get-started/overview) or [Pinecone Assistant](/guides/assistant/overview).
</Update>

<Update label="2025-02-18">
  ### Limit the number of chunks retrieved

  You can now limit the number of chunks the reranker sends to the LLM. To do this, set the `top_k` parameter (default is 15) when [retrieving context snippets](/guides/assistant/retrieve-context-snippets).
</Update>

<Update label="2025-02-21">
  ### Assistant Quickstart colab notebook

  Added the [Assistant Quickstart colab notebook](https://colab.research.google.com/github/pinecone-io/examples/blob/master/docs/assistant-quickstart.ipynb). This notebook shows you how to set up and use [Pinecone Assistant](/guides/assistant/overview) in your browser.
</Update>

<Update label="2025-02-18">
  ### Released Node.js SDK v5.0.0

  Released [`v5.0.0`](https://github.com/pinecone-io/pinecone-ts-client/releases/tag/v5.0.0) of the [Pinecone Node.js SDK](/reference/sdks/node/overview). This version uses the latest stable API version, `2025-01`, and includes support for [Pinecone Assistant](/guides/assistant/overview) and [sparse-only indexes](/guides/index-data/indexing-overview#indexes-with-sparse-vectors).
</Update>

<Update label="2025-02-11">
  ### New integrations

  Added the [Box](/integrations/box) and [Cloudera AI](/integrations/cloudera) integration pages.
</Update>

<Update label="2025-02-10">
  ### Citation highlights in assistant responses

  You can now include [highlights](/guides/assistant/chat-with-assistant#include-citation-highlights-in-the-response) in an assistant's citations. Highlights are the specific parts of the document that the assistant used to generate the response.

  Citation highlights are available in the Pinecone console or API versions `2025-04` and later.
</Update>

<Update label="2025-02-07">
  ### Pinecone API version `2025-01` is now the latest stable version

  `2025-01` is now the latest [stable version](/reference/api/versioning#release-schedule) of the [Pinecone APIs](/reference/api/introduction).
</Update>

<Update label="2025-02-07">
  ### Released Python SDK v6.0.0

  Released [`v6.0.0`](https://github.com/pinecone-io/pinecone-python-client/releases/tag/v6.0.0) of the [Pinecone Python SDK](/reference/sdks/python/overview). This version uses the latest stable API version, `2025-01`, and includes support for the following:

  * [Index tags](/guides/manage-data/manage-indexes#configure-index-tags) to categorize and identify your indexes.
  * [Integrated inference](/reference/api/introduction#inference) without the need for extra plugins. If you were using the preview functionality of integrated inference, you must uninstall the `pinecone-plugin-records` package to use the `v6.0.0` release.
  * Enum objects to help with the discoverability of some configuration options, for example, `Metric`, `AwsRegion`, `GcpRegion`, `PodType`, `EmbedModel`, `RerankModel`. This is a backwards compatible change; you can still pass string values for affected fields.
  * New client variants, `PineconeAsyncio` and `IndexAsyncio`, which provide `async` methods for use with [asyncio](https://docs.python.org/3/library/asyncio.html). This makes it possible to use Pinecone with modern async web frameworks such as [FastAPI](https://fastapi.tiangolo.com/), [Quart](https://quart.palletsprojects.com/en/latest/), and [Sanic](https://sanic.dev/en/). Async support should significantly increase the efficiency of running many upserts in parallel.

  <Warning>
    Before upgrading to `v6.0.0`, update all relevant code to account for the following [breaking changes](/reference/api/versioning#breaking-changes). See the [`v6.0.0`](https://github.com/pinecone-io/pinecone-python-client/releases/tag/v6.0.0) release notes for full details.

    * Incorporated the `pinecone-plugin-records` and `pinecone-plugin-inference` plugins into the `pinecone` package. If you are using these plugins, you must unstall them to use `v6.0.0`.
    * Dropped support for Python 3.8, which has now reached official end of life, and added support for Python 3.13.
    * Removed the explicit dependency on `tqdm`, which is used to provide a progress bar when upserting data into Pinecone. If `tqdm` is available in the environment, the Pinecone SDK will detect and use it, but `tdqm` is no longer required to run the SDK. Popular notebook platforms such as [Jupyter](https://jupyter.org/) and [Google Colab](https://colab.google/) already include `tqdm` in the environment by default, but if you are running small scripts in other environments and want to continue seeing progress bars, you will need to separately install the `tqdm` package.
    * Removed some previously deprecated and rarely used keyword arguments (`config`, `openapi_config`, and `index_api`) to instead prefer dedicated keyword arguments for individual settings such as `api_key`, `proxy_url`, etc.
  </Warning>
</Update>

<Update label="2025-02-07">
  ### Released Java SDK v4.0.0

  Released [`v4.0.0`](https://github.com/pinecone-io/pinecone-java-client/releases/tag/v4.0.0) of the [Pinecone Java SDK](/reference/sdks/java/overview). This version uses the latest stable API version, `2025-01`, and adds support for [sparse-only indexes](/guides/index-data/indexing-overview#indexes-with-sparse-vectors).

  <Warning>
    Before upgrading to `v4.0.0`, update all relevant code to account for the following [breaking changes](/reference/api/versioning#breaking-changes). See the [`v4.0.0`](https://github.com/pinecone-io/pinecone-java-client/releases/tag/v4.0.0) release notes for full details.

    * [`embed` method](/reference/api/2025-01/inference/generate-embeddings):
      * `parameters` now accepts `Map<String, Object>` instead of `EmbedRequestParameters`.
      * The `Embeddings` response class now has dense and sparse embeddings. You now must use `getDenseEmbedding()` or `getSparseEmbedding()`. For example, instead of `embeddings.getData().get(0).getValues()`, you would use `embeddings.getData().get(0).getDenseEmbedding().getValues()`.

    * [`rerank` method](/guides/search/rerank-results):
      * `documents` now accepts `List<Map<String, Object>>` instead of `List<Map<String, String>>`.
      * `parameters` now accepts `Map<String, Object>` instead of `Map<String, String>`.
  </Warning>
</Update>

<Update label="2025-02-07">
  ### Released Go SDK v3.0.0

  Released [`v3.0.0`](https://github.com/pinecone-io/go-pinecone/releases/tag/v3.0.0) of the [Pinecone Go SDK](/reference/sdks/go/overview). This version uses the latest stable API version, `2025-01`, and adds support for [sparse-only indexes](/guides/index-data/indexing-overview#indexes-with-sparse-vectors).

  <Warning>
    Before upgrading to `v3.0.0`, update all relevant code to account for the following [breaking changes](/reference/api/versioning#breaking-changes). See the [`v3.0.0`](https://github.com/pinecone-io/go-pinecone/releases/tag/v3.0.0) release notes for full details.

    * [`embed` operation](/reference/api/2025-01/inference/generate-embeddings):
      * `EmbedParameters` is no longer typed as a pointer.
    * [`create_index` operation](/guides/index-data/create-an-index):
      * `CreateServerlessIndexRequest` and `CreatePodIndexRequest` structs have been updated, and fields are now classified as pointers to better denote optionality around creating specific types of indexes: `Metric`, `Dimension`, `VectorType`, and `DeletionProtection`.
    * Various data operation:
      * `Values` in the `Vector` type are now a pointer to allow flexibility when working with sparse-only indexes.
  </Warning>
</Update>

<Update label="2025-02-07">
  ### Released .NET SDK v3.0.0

  Released [`v3.0.0`](https://github.com/pinecone-io/pinecone-dotnet-client/releases/tag/3.0.0) of the [Pinecone .NET SDK](https://github.com/pinecone-io/pinecone-dotnet-client). This version uses the latest stable API version, `2025-01`, and adds support for [sparse-only indexes](/guides/index-data/indexing-overview#indexes-with-sparse-vectors).

  <Warning>
    Before upgrading to `v3.0.0`, update all relevant code to account for the following [breaking changes](/reference/api/versioning#breaking-changes). See the [`v3.0.0`](https://github.com/pinecone-io/pinecone-dotnet-client/releases/tag/3.0.0) release notes for full details.

    * [`embed` operation](/reference/api/2025-01/inference/generate-embeddings):
      * The `Embedding` type has changed from a simple object to a discriminated union, supporting both `DenseEmbedding` and `SparseEmbedding`. New helper methods available on the Embedding type: `IsDense` and `IsSparse` for type checking, `AsDense()` and `AsSparse()` for type conversion, and `Match()` and `Visit()` for pattern matching.
      * The `Parameters` property now uses `Dictionary<string, object?>?` instead of `EmbedRequestParameters`.

    * `rerank` operation:
      * The `Document` property now uses `Dictionary<string, object?>?` instead of `Dictionary<string, string>?`.
      * The `Parameters` property now uses `Dictionary<string, object?>?` instead of `Dictionary<string, string>?`.
  </Warning>
</Update>

## January 2025

<Update label="2025-01-29">
  ### Update to the API keys page

  Added the **Created by** column on the [API keys page](https://app.pinecone.io/organizations/-/projects/-/keys) in the Pinecone Console. This column shows the email of the user who created the API key.
</Update>

<Update label="2025-01-29">
  ### Sparse-only indexes in early access

  You can now use [sparse-only indexes](/guides/index-data/indexing-overview#indexes-with-sparse-vectors) for the storage and retrieval of sparse vectors. This feature is in [early access](/release-notes/feature-availability).
</Update>

<Update label="2025-01-22">
  <img />

  Pinecone Assistant is generally available (GA) for all users.

  [Read more](https://www.pinecone.io/blog/pinecone-assistant-generally-available) about the release on our blog.
</Update>

<Update label="2025-01-09">
  ### Released Node SDK v4.1.0

  Released [`v4.1.0`](https://github.com/pinecone-io/pinecone-ts-client/releases/tag/4.1.0) of the [Pinecone Node.js SDK](/reference/sdks/node/overview). This version adds support for [index tags](/guides/manage-data/manage-indexes#configure-index-tags) when creating or configuring indexes. It also adds a new `RetryOnServerFailure` class that automatically retries asynchronous operations with exponential backoff when the server responds with a `500` or `503` [error](/reference/api/errors).
</Update>

<Update label="2025-01-09">
  ### New Billing Admin user role

  Added the Billing Admin [user role](/guides/organizations/understanding-organizations#organization-roles). Billing Admins have permissions to view billing details, usage details, and support plans.
</Update>

<Update label="2025-01-07">
  ### Released Go SDK v2.2.0

  Released [`v2.2.0`](https://github.com/pinecone-io/go-pinecone/releases/tag/v2.2.0) of the [Pinecone Go SDK](/reference/sdks/go/overview). This version adds support for [index tags](/guides/manage-data/manage-indexes#configure-index-tags) when creating or configuring indexes.
</Update>


# 2026 releases
Source: https://docs.pinecone.io/release-notes/2026

Pinecone release notes for 2026: new features, improvements, and API changes.

## August 2026

<Update label="2026-08-11">
  ### New guide: reciprocal rank fusion (RRF)

  Added a guide on [reciprocal rank fusion](/guides/search/reciprocal-rank-fusion), a client-side method for combining the results of separate searches (for example, full-text and semantic) into one ranking without normalizing scores. RRF fuses rankings rather than raw scores, so it needs no per-signal weighting.
</Update>

<Update label="2026-08-01">
  ### Released Pinecone Terraform Provider v4.0.0

  Released [v4.0.0](https://github.com/pinecone-io/terraform-provider-pinecone/releases/tag/v4.0.0) of the [Terraform Provider for Pinecone](/integrations/terraform). This version adds resources for managing [service accounts](/guides/organizations/manage-service-accounts), [role bindings](/guides/production/manage-rbac), organization invites, and removing organization members. It also adds data sources for reading existing indexes, collections, projects, service accounts, role bindings, invites, and users, and `terraform import` support for every resource.
</Update>

## July 2026

<Update label="2026-07-21">
  ### Fuzzy matching and substring search for full-text search

  [Full-text search](/guides/search/full-text-search) now supports two new ways to match text:

  * **Fuzzy matching (typo tolerance)** — In a `query_string` search, append `~` to a term to match indexed terms within a small edit distance: `body:(compxter~1)` matches `computer`. Use `term~` for an automatic distance based on term length, or `term~N` for a fixed distance (`N` is 0–2). Fuzzy works on existing indexes with no reindex. See [Fuzzy matching](/guides/search/full-text-search#query-syntax-reference).
  * **Substring search with n-grams** — Configure a text field for character n-gram tokenization to match on partial words, prefixes, and autocomplete-style queries. Add an `ngram` object (`min_gram`, `max_gram`, `prefix_only`) to a field's `full_text_search` config at index creation, then query it with ordinary `text` or `query_string` searches. See [Substring search with n-grams](/guides/search/full-text-search#substring-search-with-n-grams).

  Full-text search remains in [public preview](/release-notes/feature-availability) under API version `2026-01.alpha`.
</Update>

<Update label="2026-07-20">
  ### Manage roles from your identity provider with SAML and SCIM

  Organizations on the Enterprise plan with SSO can now manage Pinecone roles directly from their identity provider (IdP), instead of assigning them manually in Pinecone. Two modes are available:

  * **SAML role management** sets each user's organization and project roles from a SAML attribute on every SSO login.
  * **SCIM provisioning** syncs members and their roles in real time as you add, update, deactivate, or remove them in your IdP.

  Both modes use the same `pinecone:*` role values and work with Okta and other SAML 2.0 / SCIM 2.0 providers. Configure them under **Settings > Access > Identity provider** in the Pinecone console. For more information, see [Manage roles with Okta](/guides/production/configure-single-sign-on/okta-role-management) and [SCIM provisioning with Okta](/guides/production/configure-single-sign-on/okta-scim-provisioning).
</Update>

<Update label="2026-07-13">
  ### Expanded role-based access controls (RBAC)

  Pinecone now offers an expanded set of roles for managing access to organizations and projects. New **Organization member** and **Project member** roles grant more restricted access than the owner and manager roles, and projects now support granular editor and viewer roles (project, control plane, and data plane) that you can assign to users, service accounts, and API keys.

  To better communicate the access hierarchy, organization owners are now shown in each project's member list. This replaces the separate project-role assignments that could fall out of sync with the access organization owners inherit to all projects. Effective permissions are unchanged.

  If you used the previous role model, the **User** role has been renamed to **Manager**: the organization-level **User** role is now **Organization manager**, and the project-level **User** role is now **Project manager**. This is a name change only—permissions are unchanged and existing assignments are migrated automatically.

  You can assign and manage roles in the [Pinecone console](https://app.pinecone.io) or programmatically with the Admin API. For more information, see [Manage roles and access](/guides/production/manage-rbac), [Organization roles](/guides/organizations/understanding-organizations#organization-roles), and [Project roles](/guides/projects/understanding-projects#project-roles).
</Update>

<Update label="2026-07-02">
  ### Public preview: Restore a backup to a different region

  You can now restore a [serverless backup](/guides/manage-data/backups-overview) into a different region on the same cloud provider. Use the `unstable` version of the create index endpoint, specifying the backup as `source_backup_id` within `spec.serverless` and the target region there. Restoring to a different cloud provider is not supported, and the feature is currently available through the REST API only.

  For details, see [Restore to a different region](/guides/manage-data/restore-an-index#restore-to-a-different-region).
</Update>

<Update label="2026-07-01">
  ### Cohere Rerank 4.0 Fast is generally available, and cohere-rerank-3.5 is deprecated

  [`cohere-rerank-4-fast`](/models/cohere-rerank-4-fast) (Cohere Rerank 4.0 Fast) is now generally available as a [reranking model](/guides/search/rerank-results#reranking-models) on Pinecone. It succeeds `cohere-rerank-3.5`, improves relevance quality, and supports multiple rerank fields. Cohere Rerank 4.0 is hosted on Azure AI under the Global Standard deployment type, and requests may be processed in regions outside the United States.

  With this release, [`cohere-rerank-3.5`](/models/cohere-rerank-3.5) is **deprecated**:

  * **Through July 31, 2026**: `cohere-rerank-3.5` continues to serve requests as before.
  * **August 1, 2026**: requests to `cohere-rerank-3.5` are automatically served by `cohere-rerank-4-fast`.

  No code change is required for the transition, but note two differences before you migrate:

  * **Relevance scores differ.** `cohere-rerank-4-fast` returns different scores than `cohere-rerank-3.5`. If your application relies on hard-coded score thresholds, re-tune them against `cohere-rerank-4-fast` before August 1.
  * **Billing counts units differently.** The per-unit rate is unchanged at \$2.00 per 1,000 rerank units. One rerank unit covers a query plus up to 100 documents, with documents longer than \~500 tokens auto-chunked into \~500-token chunks that each count toward that 100. As a result, `cohere-rerank-4-fast` can bill multiple units for a large request, whereas `cohere-rerank-3.5` billed one unit per request.

  To control the transition yourself, migrate your rerank requests to `cohere-rerank-4-fast` before August 1. For model details and parameters, see [Reranking models](/guides/search/rerank-results#reranking-models).
</Update>

## June 2026

<Update label="2026-06-03">
  ### Multi-region and multi-cloud support on the Builder plan

  The [Builder plan](https://www.pinecone.io/pricing/) now supports serverless indexes in every generally available cloud region, the same regions available on the Standard and Enterprise plans. Previously, Builder indexes were limited to the `us-east-1` region of AWS.

  Highlights:

  * **All supported regions** — Create Builder serverless indexes across AWS, GCP, and Azure, including `us-west-2` (Oregon), `eu-west-1` (Ireland), `eu-central-1` (Frankfurt), `ap-southeast-1` (Singapore), `us-central1` (Iowa), `europe-west4` (Netherlands), and `eastus2` (Virginia).
  * **Lower latency and data residency** — Deploy indexes closer to your application or in a region that meets your data residency requirements, without upgrading to Standard or Enterprise.
  * **No pricing change** — Builder remains a flat \$20/month plan with no usage overages.

  The Starter plan continues to support the `us-east-1` region of AWS only. For the full list of supported regions, see [Cloud regions](/guides/index-data/create-an-index#cloud-regions). For plan quotas, see [Database limits](/reference/api/database-limits).
</Update>

<Update label="2026-06-01">
  ### Cheaper bulk imports and free import credit

  [Importing from object storage](/guides/index-data/import-data) is now cheaper: the bulk-import overage rate is **\$0.25/GB**, down from \$1/GB.

  In addition, **Standard and Enterprise** organizations now get a **one-time \$250 bulk import credit** (1 TB), valid through July 31, 2026. Usage beyond the credit is billed at the new \$0.25/GB rate. Builder and Starter plans are not eligible.

  For details, see [Understanding cost — Imports](/guides/manage-cost/understanding-cost#imports).
</Update>

## May 2026

<Update label="2026-05-05">
  ### Public preview: Pinecone Marketplace

  [Pinecone Marketplace](/guides/marketplace/overview) is now in [public preview](/release-notes/feature-availability). Marketplace lets you build, publish, and operate AI-powered knowledge applications on top of Pinecone, with a managed deployment lifecycle and end-user chat interface.

  Highlights:

  * **Templates and connectors** — Start from pre-built templates, connect data sources (Google Drive, manual upload), and configure knowledge processing with the Knowledge Agent Toolkit (KAT).
  * **Multi-domain routing** — Route end-user queries across multiple knowledge domains within a single deployment.
  * **Evaluations and analytics** — Run evaluations against your deployment and monitor usage with event logs.
  * **Versioning and rollback** — Publish deployment versions and roll back to previous configurations.
  * **End-user experience** — Authenticated chat interface with citations, visual components, and feedback collection.
  * **Increased Starter plan limits** - The Starter plan is currently offering 1M input tokens per month (500K before promotion) to help explore Marketplace apps until June 30, 2026.

  For details, see the [Marketplace quickstart](/guides/marketplace/quickstart) and [Marketplace API reference](/reference/api/marketplace/introduction).
</Update>

<Update label="2026-05-04">
  ### New Builder plan

  The [Builder plan](https://www.pinecone.io/pricing/) is now available at **\$20/month** (flat). Builder is designed for individual developers who need higher limits than Starter without committing to usage-based pricing. Key differences from Starter:

  * **10 serverless indexes** (up from 5)
  * **10 GB storage per organization**
  * **100 namespaces per index** (up from 20)
  * **Prometheus and Datadog monitoring**

  Builder is a fixed-price plan with no overages. When you hit a quota, operations are blocked rather than billed. Payment is by credit or debit card only. You can upgrade from Starter or downgrade from Standard at any time in the Pinecone console.

  For full quotas, see [Database limits](/reference/api/database-limits). For billing details, see [Understanding cost](/guides/manage-cost/understanding-cost).
</Update>

<Update label="2026-05-04">
  ### Public preview: Full-text search

  [Full-text search](/guides/search/full-text-search) is now in [public preview](/release-notes/feature-availability). Full-text search uses a typed document model: you upsert data as JSON documents, declare ranking fields in a schema, and Pinecone indexes them accordingly. Schema field types: `string` with `full_text_search` (indexed for BM25 ranking), `dense_vector`, and `sparse_vector`. Any other fields you upsert are stored as metadata and automatically indexed for filtering — no schema declaration required.

  Highlights:

  * **Four scoring methods** via `score_by`: `text` (BM25), `query_string` (Lucene syntax, including cross-field boolean queries), `dense_vector`, and `sparse_vector`.
  * **New data plane endpoints** under `/namespaces/{namespace}/documents/`: `upsert`, `search`, `fetch`, and `delete`.
  * **New filter operator** `$match_phrase` for phrase matching against text fields, composable with any `score_by` method.
  * **Flexible deployment**: on-demand read capacity (`read_capacity.mode: "OnDemand"`) and dedicated read capacity (`read_capacity.mode: "Dedicated"`) are both supported on managed (serverless) indexes.

  Use API version `2026-01.alpha` to access the feature.
</Update>

<Update label="2026-05-01">
  ### New AWS regions for serverless indexes

  You can now deploy [serverless indexes](/guides/index-data/indexing-overview) in two new AWS regions: `eu-central-1` (Frankfurt) and `ap-southeast-1` (Singapore). Both regions are available on Standard and Enterprise plans. For the full list of supported regions, see [Cloud regions](/guides/index-data/create-an-index#cloud-regions).
</Update>

## April 2026

<Update label="2026-04-28">
  ### General availability: Fetch by metadata

  The [Fetch by metadata](/reference/api/latest/data-plane/fetch_by_metadata) operation is now [generally available](/release-notes/feature-availability) and recommended for production usage. Use a metadata filter expression to fetch matching records without knowing their IDs, and paginate with `paginationToken` to retrieve result sets larger than 10,000 records per response.

  For more information, see [Fetch records by metadata](/guides/manage-data/fetch-data#fetch-records-by-metadata).
</Update>

<Update label="2026-04-21">
  ### Upsert files with custom IDs in Assistant

  Pinecone Assistant now supports [upserting files](/guides/assistant/upload-files#upsert-a-file) with user-provided file IDs, so you can create or replace a file by a stable custom identifier instead of relying on system-generated UUIDs. For more information, see [File identifiers](/guides/assistant/files-overview#file-identifiers).

  As part of this update, [upload](/guides/assistant/upload-files), upsert, and delete operations now return an operation object that can be polled for status and progress. Assistant also includes new API endpoints to [list and describe file operations](/guides/assistant/manage-files#track-file-operations).

  This update applies to the API only; SDK support is not yet available.
</Update>

<Update label="2026-04-15">
  ### General availability: Dedicated Read Nodes

  [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are now [generally available](/release-notes/feature-availability) and recommended for production usage on Standard and Enterprise plans. You can provision read hardware for large, high-throughput indexes that need predictable, low latency using the console and API.
</Update>

<Update label="2026-04-01">
  ### Pinecone Assistant usage-based pricing and monthly Starter limits

  Pinecone Assistant pricing is now fully usage-based. The hourly per-assistant fee has been removed. On Standard and Enterprise, you pay for what you use: ingestion (file uploads and updates on an assistant), storage, and chat, context, and evaluation tokens — with no base charge per assistant.

  For the Starter plan, Assistant included allowances are now monthly and reset each billing period (they are no longer all-time project totals). Starter includes **500,000 chat input tokens, 300,000 chat output tokens, 500,000 context retrieval tokens, and 1,000 ingestion units** per month. When you upload files to an assistant, usage is measured in ingestion units (approximately one unit per chunk, \~400 tokens); multimodal PDF chunks account for more ingestion units per chunk than standard text on the same meter.

  Per-assistant file count limits have been removed for all plans. Usage is governed by ingestion and storage allowances, file size and page limits, and rate limits instead of a cap on the number of stored documents.

  For details, see [Pricing and limits](/guides/assistant/pricing-and-limits) and [Pinecone pricing](https://www.pinecone.io/pricing/).
</Update>

## March 2026

<Update label="2026-03-26">
  ### General availability: platform and operations features

  The following capabilities are now [generally available](/release-notes/feature-availability) and recommended for production usage:

  * **Namespace creation** — [Create namespace API](/guides/manage-data/manage-namespaces)
  * **Pinecone MCP server** — [Integrate AI agents with Pinecone](/guides/operations/mcp-server)
  * **Assistant MCP server** — [Use an Assistant MCP server](/guides/assistant/mcp-server)
  * **Bulk metadata updates** — [Update metadata across multiple records](/guides/manage-data/update-data#update-metadata-across-multiple-records)
  * **Customer-managed encryption keys (CMEK)** — [Configure CMEK](/guides/production/configure-cmek)
  * **Data import from object storage** (Amazon S3, Google Cloud Storage, Azure Blob Storage) — [Import records](/guides/index-data/import-data)
  * **Audit logs** — [Configure audit logs](/guides/production/configure-audit-logs)
  * **Admin API and service accounts** (organization- and project-level) — [Manage service accounts](/guides/organizations/manage-service-accounts), [Manage service accounts at the project level](/guides/projects/manage-service-accounts)
  * **Backups and restore** (serverless indexes) — [Back up an index](/guides/manage-data/back-up-an-index), [Restore an index](/guides/manage-data/restore-an-index)
  * **Pinecone Local** (local development emulator) — [Local development](/guides/operations/local-development)
  * **Automated testing with Pinecone Local** — [Automated testing](/guides/production/automated-testing)
  * **Indexes with sparse vectors** — [Indexes with sparse vectors](/guides/index-data/indexing-overview#indexes-with-sparse-vectors)
  * **`pinecone-sparse-english-v0`** — [Sparse English embedding model](/guides/search/rerank-results#pinecone-sparse-english-v0)
  * **Prometheus monitoring** (serverless indexes) — [Monitor with Prometheus](/guides/production/monitoring#monitor-with-prometheus)
  * **Evaluate answers (`metrics_alignment`)** — [Evaluate answers](/guides/assistant/evaluate-answers)
  * **Manage storage integrations** — [Manage storage integrations](/guides/operations/integrations/manage-storage-integrations)
</Update>

<Update label="2026-03-03">
  ### Released Pinecone Terraform Provider v3.0.0

  Released [v3.0.0](https://github.com/pinecone-io/terraform-provider-pinecone/releases/tag/v3.0.0) of the [Terraform Provider for Pinecone](/integrations/terraform). This version adds support for [BYOC indexes](/guides/production/bring-your-own-cloud), [dedicated read nodes](/guides/index-data/dedicated-read-nodes), and [metadata indexing](/guides/index-data/create-an-index#metadata-indexing) on serverless and BYOC indexes.
</Update>

## February 2026

<Update label="2026-02-19">
  ### BYOC now available on AWS, GCP, and Azure

  [Bring Your Own Cloud (BYOC)](/guides/production/bring-your-own-cloud) is now available in [public preview](/release-notes/feature-availability) on AWS, GCP, and Azure. BYOC lets you run Pinecone's data plane inside your own cloud account with a zero-access operating model — Pinecone never needs SSH, VPN, or inbound network access to your infrastructure.

  Deploy using a self-serve Pulumi-based setup wizard, with pull-based operations that execute locally in your cluster. Your vectors, metadata, and queries never leave your environment.
</Update>

<Update label="2026-02-01">
  ### HIPAA compliance add-on for Standard plan

  HIPAA compliance is now available as an optional add-on for [Standard plan](https://www.pinecone.io/pricing/) customers. For **\$190 per month**, you get HIPAA-ready infrastructure, encrypted data storage, audit logging, enhanced security controls, and BAA execution and compliance documentation support.

  Full HIPAA compliance remains included with the Enterprise plan. To enable the add-on on the Standard plan, [contact sales](mailto:sales@pinecone.io) or see [Understanding cost — HIPAA compliance add-on](/guides/manage-cost/understanding-cost#hipaa-compliance-add-on).
</Update>

## January 2026

<Update label="2026-01-28">
  ### Claude model deprecation for Assistant

  Anthropic has [deprecated](https://platform.claude.com/docs/en/about-claude/model-deprecations) the Claude 3.5 Sonnet and Claude 3.7 Sonnet models. Pinecone Assistant automatically routes all chat requests that specify `claude-3-5-sonnet` or `claude-3-7-sonnet` to Claude Sonnet 4.5, which provides enhanced intelligence at the same price. No code changes are required.

  To update your code to explicitly use Claude Sonnet 4.5, set `model: "claude-sonnet-4-5"` in your chat requests. For more information, see [Choose a model](/guides/assistant/chat-with-assistant#choose-a-model).
</Update>

<Update label="2026-01-28">
  ### Pinecone Assistant node for n8n

  The official Pinecone Assistant n8n node brings Assistant's end-to-end RAG capabilities directly into n8n workflows, letting you connect any data source to AI-backed automation.

  For more information, see the [Assistant quickstart for n8n](/guides/assistant/quickstart/n8n-quickstart).
</Update>

<Update label="2026-01-27">
  ### Claude Sonnet 4.5 now available for Assistant chat

  Pinecone Assistant now supports Anthropic's Claude Sonnet 4.5 model. To use this model, set `model: "claude-sonnet-4-5"` in your [chat](/reference/api/latest/assistant/chat_assistant) requests. In the Pinecone console, Claude Sonnet 4.5 is also available as a selection in the **Chat model** dropdown menu in the playground for each assistant.

  For more information, see [Choose a model](/guides/assistant/chat-with-assistant#choose-a-model).
</Update>

<Update label="2026-01-23">
  ### Metadata filter limit: 10,000 values per `$in`/`$nin` operator

  Pinecone now enforces a limit of 10,000 values per `$in` or `$nin` operator in metadata filter expressions. This limit helps ensure consistent query performance and protects shared infrastructure from excessive load caused by very large filters.

  Requests that exceed this limit will fail with a `400 - BAD_REQUEST` error.

  If your application currently uses large `$in` filters (especially for access control), consider these approaches:

  * **Namespace-based isolation** (recommended): Create separate namespaces for each tenant instead of filtering by thousands of tenant IDs. This can also reduce query costs (queries on a 1 GB namespace cost 1 RU instead of 100 RUs for a 100 GB namespace with filtering).
  * **Access control groups**: Filter by organization, project, or role identifiers instead of individual user IDs.
  * **Post-filter client-side**: Retrieve a larger top K without filtering, then filter results in your application.

  For more information, see [Metadata filter limits](/reference/api/database-limits#metadata-filter-limits) and [Design for multi-tenancy](/guides/index-data/data-modeling#design-for-multi-tenancy).
</Update>

<Update label="2026-01-16">
  ### Request-per-second limits for data plane operations

  Pinecone now enforces request-per-second rate limits on data plane operations (query, upsert, delete, and update) at the namespace level. These limits are set to 100 requests per second per namespace for all plans and provide protection against excessive request rates.

  Request-per-second limits are enforced in addition to existing read unit and write unit limits. If you exceed a request-per-second limit, you'll receive a `429 - TOO_MANY_REQUESTS` error.

  For more information, see [Database limits](/reference/api/database-limits#data-plane-operations-requests-per-second-limits).
</Update>

<Update label="2026-01-15">
  ### Pagination support for fetch by metadata

  The [Fetch by metadata](/reference/api/latest/data-plane/fetch_by_metadata) operation now supports pagination, allowing you to fetch large result sets in multiple requests. Use the `paginationToken` parameter to retrieve the next page of results.

  When there are more results available, the response includes a `pagination` object with a `next` token. Pass this token as the `paginationToken` parameter in subsequent requests to fetch the next page. When there are no more results, the response does not include a `pagination` object.

  For more information, see [Fetch records by metadata](/guides/manage-data/fetch-data#fetch-records-by-metadata).
</Update>


# Feature availability
Source: https://docs.pinecone.io/release-notes/feature-availability

Pinecone feature availability across public preview, general availability, and limited availability releases, with links to release notes.

This page defines the different availability phases of a feature in Pinecone.

The availability phases are used to communicate the maturity and stability of a feature. The availability phases are:

* **Early access**: In active development and may change at any time. Intended for user feedback only. In some cases, users must be granted explicit access to the API by Pinecone.

* **Public preview**: Unlikely to change between public preview and general availability. Not recommended for production usage. Available to all users.

* **Limited availability**: Available to select customers in a subset of regions and providers for production usage.

* **General availability**: Will not change on short notice. Recommended for production usage. Officially [supported by Pinecone](/troubleshooting/pinecone-support-slas) for non-production and production usage.

* **Deprecated**: Still supported, but no longer under active development, except for critical security fixes. Existing usage will continue to function, but migration following the upgrade guide is strongly recommended. Will be removed in the future at an announced date.

* **End of life (EOL)**: Removed, and no longer supported or available.

<Note>
  A feature is in **general availability** unless explicitly marked otherwise.
</Note>


# Billing disputes and refunds
Source: https://docs.pinecone.io/troubleshooting/billing-disputes-and-refunds

Troubleshoot “Billing disputes and refunds” in Pinecone: As a rule, Pinecone does not offer refunds for unused indexes. If you use a pod-based index, we.

As a rule, Pinecone does not offer refunds for unused indexes. If you use a pod-based index, we charge only for the pods you use to create it, not per API call or query. Whether you have used your index or not does not factor into our billing.

Our serverless indexes are a better fit if you don't plan to use your index on a regular basis. Serverless indexes are billed by the number of reads and writes you run and how much storage your index consumes. If your bill for your pod-based index is too high, we recommend [migrating to a serverless index](/guides/indexes/pods/migrate-a-pod-based-index-to-serverless) instead.

Our billing policies are detailed in our [user agreement](https://www.pinecone.io/user-agreement/) and [pricing page](https://pinecone.io/pricing).

We have several resources available to help you manage your bill:

* [Account deactivation for non-payment](/guides/organizations/manage-billing/non-payment-account-deactivation)
* [Change your billing plan](/guides/organizations/manage-billing/upgrade-billing-plan)
* [Monitor your usage and costs](/guides/manage-cost/monitor-usage-and-costs)
* [Understand cost](/guides/manage-cost/understanding-cost)
* [Manage cost](/guides/manage-cost/manage-cost)


# Contact Support
Source: https://docs.pinecone.io/troubleshooting/contact-support

Troubleshoot “Contact Support” in Pinecone: Pinecone Support is available to customers on the Builder and Standard billing plans.

Pinecone Support is available to customers on the **Builder**, **Standard**, and **Enterprise** billing plans.

First-response SLAs only apply to tickets created by users in an organization subscribed to a [support plan](https://www.pinecone.io/pricing/?plans=support). To upgrade your support plan, go to [Manage your support plan](https://app.pinecone.io/organizations/-/settings/support/plans) in the console and select your desired plan. Before subscribing to a support plan, you must [Upgrade your billing plan](/guides/organizations/manage-billing/upgrade-billing-plan) to the **Builder**, **Standard**, or **Enterprise** billing plan.

Our business hours are Monday to Friday from 8:00 AM to 8:00 PM Eastern Time. We are closed on US federal holidays. Customers subscribed to the **Pro** or **Premium** support plan have 24/7/365 on-call availability, which is triggered by creating a SEV-1 ticket.

All customers subscribed to a support plan can create tickets in the Pinecone console. To create a ticket, go to the [Help center](https://app.pinecone.io/organizations/-/settings/support/ticket), select [Create a ticket](https://app.pinecone.io/organizations/-/settings/support/ticket/create), and fill out the form.

If you are not subscribed to a support plan and need help logging into the console, upgrading your support or billing plan, or have questions about billing, please complete the [public support contact form](https://www.pinecone.io/contact/support/) and we will respond if necessary.

If you have general questions about the platform, pricing, events, and more, [contact our sales team](https://www.pinecone.io/contact/). For inquiries about partnerships, please [contact the Pinecone Partner Program](https://www.pinecone.io/partners/#sales-contact-form-submissions).


# CORS Issues
Source: https://docs.pinecone.io/troubleshooting/cors-issues

Troubleshoot Pinecone CORS errors and Access-Control-Allow-Origin issues when calling the API from localhost or browser-based web apps.

Cross-Origin Resource Sharing (CORS) is an HTTP-header based security feature that
allows a server to indicate which domains, schemes or ports a browser should accept
content from. When a browser-based app, by default, only loads content from the same
origin as the original request, CORS errors can appear if the responses come from
a different origin. Pinecone's current implementation of CORS can cause this mismatch
and display the following error:

```console console theme={null}
No 'Access-Control-Allow-Origin' header is present on the requested resource.
```

This error occurs in response to cross-origin requests. Most commonly, it occurs when a user is running a local web server with the hostname `localhost`, which Pinecone's Same Origin Policy (SOP) treats as distinct from the IP address of the local machine.

To resolve this issue, host your web server on an external server with a public IP address and DNS name entry.

### About Localhost (running a web server locally)

Localhost is not inherently a problem. However, when running a web server on a local machine (e.g., laptop or desktop computer), using "localhost" as the hostname can cause issues with cross-origin resource sharing (CORS).

The reason for this is that the Same-Origin Policy (SOP) enforced by web browsers treats "localhost" as a different origin than the actual IP address of the machine. For example, if a web application running on "localhost" makes a cross-origin request to a server running on the actual IP address of the machine, the browser will treat it as a cross-origin request and enforce the SOP.

To allow cross-origin requests between "localhost" and the actual IP address of the machine, the server needs to explicitly allow them by including the appropriate CORS headers in its response. However, as mentioned earlier, running a web server on a local machine can present security risks and is generally not recommended for production use.

Therefore, while "localhost" itself is not a problem, using it as the hostname for a web server can cause CORS issues that need to be properly addressed. Additionally, running a web server on a local machine should be done with caution and only for development or testing purposes, rather than for production use.


# Custom data processing agreements
Source: https://docs.pinecone.io/troubleshooting/custom-data-processing-agreements

Request a custom data processing agreement (DPA) with Pinecone if your team requires terms beyond the standard agreement available on the Pinecone website.

If you need a data processing agreement (DPA) with Pinecone you can get started by filling out the form in our [Security Center](https://security.pinecone.io/). You'll need to request access first. Simply click the "Get Access" box on that page and enter your information. You should receive a link with further instructions shortly.


# Debug model vs. Pinecone recall issues
Source: https://docs.pinecone.io/troubleshooting/debug-model-vs-pinecone-recall-issues

Troubleshoot “Debug model vs. Pinecone recall issues” in Pinecone: Before starting, establish an evaluation framework for your model and Pinecone recall.

## **Step 1: Establish the evaluation framework**

Before starting, establish an evaluation framework for your model and Pinecone recall issues. You will need to query a dataset of at least 10 samples and a source dataset of 100k samples, and choose an evaluation metric that is appropriate for your use case. Pinecone recommends [Evaluation Measures in Information Retrieval](https://www.pinecone.io/learn/offline-evaluation/) as a guide for choosing an evaluation metric. Label the "right answers" in the source dataset for each query.

## **Step 2: Generate embeddings for queries + source dataset with the model**

Use your model to generate embeddings for your queries and the source dataset. Run the model on the source dataset to create the vector dataset and query vectors.

## **Step 3: Calculate brute force vector distance to evaluate model quality**

Run a brute force search using query vectors over the vector dataset via FAISS or numpy and record the record IDs for each query. Evaluate the returned list using your evaluation metric and the set of "right answers" labeled in step 1. If this metric is unacceptable, it indicates a model issue.

## **Step 4: Upload vector dataset to Pinecone + query**

Upload the vector dataset to Pinecone and query it using your queries. Record the vector IDs returned for each query.

## **Step 5: Calculate Pinecone recall**

For each query, compare the % of vector IDs that Pinecone recalled compared to the brute force search. This will be the % recall for each query. You can then average across all queries to get average recall. Typically, average recall should be close to 0.99 for s1/p1 indexes.

## **Step 6: If recall is too low, reach out to Pinecone Support (reproducible dataset and queries)**

If the recall metric is too low for your use case, reach out to Pinecone product and engineering with the query and vector dataset that reproduces the issue for further investigation. Pinecone's team will investigate.


# Delete your account
Source: https://docs.pinecone.io/troubleshooting/delete-your-account

Troubleshoot “Delete your account” in Pinecone: To delete your Pinecone account, you need to remove your user from all organizations and delete any.

To delete your Pinecone account, you need to remove your user from all organizations and delete any organizations in which you are the sole member.

<Warning>These actions cannot be undone.</Warning>

* [How do I remove myself from an organization?](/guides/organizations/manage-organization-members#remove-a-member)
* [How do I delete an organization?](/troubleshooting/delete-your-organization)

Once you've removed yourself from or deleted all organizations associated with your user, your Pinecone account no longer exists.


# Delete your organization
Source: https://docs.pinecone.io/troubleshooting/delete-your-organization

Troubleshoot “Delete your organization” in Pinecone: If you want to delete your Pinecone organization entirely, you'll need to delete all projects, which.

If you want to delete your Pinecone organization entirely, you'll need to delete all projects, which first requires deleting all indexes and collections, and downgrade to the Starter plan.

* [Delete an index](/guides/manage-data/manage-indexes#delete-an-index)
* [Delete a project](/guides/projects/manage-projects#delete-a-project)
* [Downgrade to the Starter plan](/guides/organizations/manage-billing/downgrade-billing-plan)

Once you've downgraded to the Starter plan and deleted your indexes and projects, you can delete your organization.

<Note>This action cannot be undone.</Note>

1. Go to [Settings > Manage](https://app.pinecone.io/organizations/-/settings/manage) in the Pinecone console.
2. Click **Delete this organization**.
3. Type the organization name and confirm the deletion.


# Embedding values changed when upserted
Source: https://docs.pinecone.io/troubleshooting/embedding-values-changed-when-upserted

Diagnose why Pinecone embedding values appear changed after upsert, including float32 precision rounding and how the API serializes numeric vector data.

There are two distinct cases in which you might notice that the values of your embeddings appear different in Pinecone than the floats you upserted.

If you use a pod-based index with `p2` pods, we use quantization to enable the [Pinecone Graph Algorithm.](https://www.pinecone.io/blog/hnsw-not-enough/#:~:text=built%20vector%20databases.-,The%20Pinecone%20Graph%20Algorithm,-In%20order%20to) This is utilized only in `p2` indexes and powers faster query paths and greater QPS capacities.

For all serverless and other pod-based indexes, you may see slightly different values in Pinecone for high-precision floats. What’s happening here is a result of the fact that fractions can’t be accurately represented in fixed amounts of memory. Different numbers might be mapped to the same bit representation, according to a standard known as [IEEE 754](https://en.wikipedia.org/wiki/IEEE_754). More specifically, at Pinecone, we use Rust’s `f32` type, which is more commonly known as a `float` in Java, C, C++, and Python.

If you take these numbers and look at their physical memory representation, you’ll see that each float maps to the same representation before and after we upsert the vector to Pinecone. Our team built a [small demonstration in Rust](https://play.rust-lang.org/?version=stable\&mode=debug\&edition=2021\&gist=3584c20894714c5cba47127a036678fa) that you can use to explore some examples. We've also included a sample result in the attached screenshot.

This behavior is common across every system in the world, and the general trend in machine learning has been to reduce accuracy even more (see Google’s [bfloat16](https://en.wikipedia.org/wiki/Bfloat16_floating-point_format), which is now also standardized).

<img alt="A screenshot of the Rust demonstration, showing that two different floats have the same memory representation in bits." />


# Error: Cannot import name 'Pinecone' from 'pinecone'
Source: https://docs.pinecone.io/troubleshooting/error-cannot-import-name-pinecone

Troubleshoot “Error: Cannot import name 'Pinecone' from 'pinecone'” in Pinecone: When using an older version of the Python SDK (earlier than 3.0.0), trying.

## Problem

When using an older version of the [Python SDK](https://github.com/pinecone-io/pinecone-python-client) (earlier than 3.0.0), trying to import the `Pinecone` class raises the following error:

```console console theme={null}
ImportError: cannot import name 'Pinecone' from 'pinecone'
```

## Solution

Upgrade the SDK version and try again:

```Shell Shell theme={null}
# If you're interacting with Pinecone via HTTP requests, use:
pip install pinecone --upgrade
```

```Shell Shell theme={null}
# If you're interacting with Pinecone via gRPC, use:
pip install "pinecone[grpc]" --upgrade
```


# Error: Handshake read failed when connecting
Source: https://docs.pinecone.io/troubleshooting/error-handshake-read-failed

Troubleshoot “Error: Handshake read failed when connecting” in Pinecone: When trying to connect to Pinecone server, some users may receive an error message.

## Problem

When trying to connect to Pinecone server, some users may receive an error message that says `Handshake read failed` and their connection attempt fails. This error can prevent them from running queries against their Pinecone indexes.

## Solution

If you encounter this error message, it means that your computer is not properly connecting with the Pinecone server. The error is often due to a misconfiguration of your Pinecone client or API key. Here is a recommended solution:

1. Make sure your firewall is not blocking any traffic and your internet connection is working fine. If you are unsure about how to do this, please consult your IT team.
2. Check that you have set up the Pinecone client and API key correctly. Double-check that you have followed the instructions in our [documentation](/guides/get-started/quickstart) correctly.
3. If you are still having issues, try creating a new index on Pinecone and populating it with data by running another script on your computer. This will verify that your computer can access the Pinecone servers for some tasks.
4. If the error persists, you may need to check your code for any misconfigurations. Make sure you are setting up your Pinecone client correctly and passing the right parameters when running queries against your indexes.
5. If you are still unable to resolve the issue, you can reach out to Pinecone support for assistance. They will be able to help you diagnose and resolve the issue.

## Conclusion

If you encounter the `Handshake read failed` error when trying to connect to Pinecone server, there are several steps you can take to resolve the issue. First, double-check that you have set up the Pinecone client and API key correctly. Then, check for any misconfigurations in your code. If the error persists, [contact Pinecone Support](/troubleshooting/contact-support) for assistance.


# How to work with Support
Source: https://docs.pinecone.io/troubleshooting/how-to-work-with-support

Troubleshoot “How to work with Support” in Pinecone: There are several best practices for working with Pinecone Support that can lead to faster resolutions.

There are several best practices for working with Pinecone Support that can lead to faster resolutions and more relevant recommendations. Please note that Pinecone Support is reserved for users in organizations on the Standard or Enterprise plan. First-response SLAs only apply to tickets created by users in an organization subscribed to a [support plan](https://www.pinecone.io/pricing/?plans=support). To upgrade your support plan, go to [Manage your support plan](https://app.pinecone.io/organizations/-/settings/support/plans) in the console and select your desired plan.

## Utilize Pinecone AI Support

Our [support chatbot](https://app.pinecone.io/organizations/-/settings/support) is knowledgeable of our documentation, troubleshooting articles, website and more. Many of your questions can be answered immediately using this resource. We also review all interactions with the support chatbot and constantly make improvements.

## Use the email associated with your Pinecone account

We map your account information to the tier of your organization to assign appropriate SLAs. If you open tickets using an email not associated with your Pinecone account, we will close your request and suggest alternative contact methods.

## Create tickets using the support portal

Instead of creating tickets via email, use the [Help center](https://app.pinecone.io/organizations/-/settings/support) in the Pinecone console to create tickets. The form allows you to provide helpful information such as severity and category. Furthermore, the conversation format will be much more digestible in the portal, especially when involving code snippets and other attachments.

## Select an appropriate severity

Pinecone Support reserves the right to change the ticket severity after our initial response and assessment of the case. Note that a Sev-1 ticket indicates that your production environment is completely unavailable, and a Sev-2 ticket indicates that your production environment has degraded performance. If your issue does not involve a production-level usage or application, please refrain from opening Sev-1 or Sev-2 tickets.

## Provide the exact names of impacted indexes and projects

When opening a ticket that involves specific resources in your organization, please specify the name of the impacted index(es) and project(s).

## Provide as detailed a description as possible

Please include code snippets, version specifications, and the full stack trace of error messages you encounter. Whenever possible, please include screenshots or screen recordings. The more information you provide, the more likely we can effectively assist you in our first response, and you can return to building with Pinecone.


# Serverless index creation error - max serverless indexes
Source: https://docs.pinecone.io/troubleshooting/index-creation-error-max-serverless

Resolve the Pinecone serverless index creation error caused by hitting the 20-index project limit by deleting unused indexes or upgrading your plan.

## Problem

Each project is limited to 20 serverless indexes. Trying to create more than 20 serverless indexes in a project raises the following `403 (FORBIDDEN)` error:

```console console theme={null}
This project already contains 20 serverless indexes, the maximum per project. 
Delete any unused indexes and try again, or create a new project for more serverless indexes. 
For additional help, please contact support@pinecone.io.
```

## Solution

[Delete any unused serverless indexes](/guides/manage-data/manage-indexes#delete-an-index) in the project and try again, or create a new project to hold additional serverless indexes.

Also consider using [namespaces](/guides/index-data/indexing-overview#namespaces) to partition vectors of the same dimensionality within a single index. Namespaces can help speed up queries as well as comply with [multitenancy](/guides/index-data/implement-multitenancy) requirements.


# Index creation error - missing spec parameter
Source: https://docs.pinecone.io/troubleshooting/index-creation-error-missing-spec

Troubleshoot “Index creation error - missing spec parameter” in Pinecone: Using the new API, creating an index requires passing appropriate values into the.

## Problem

Using the [new API](/reference/api), creating an index requires passing appropriate values into the `spec` parameter. Without this `spec` parameter, the `create_index` method raises the following error:

```console console theme={null}
TypeError: Pinecone.create_index() missing 1 required positional argument: 'spec'
```

## Solution

Set the `spec` parameter. For guidance on how to set this parameter, see [Create an index](/guides/index-data/create-an-index#create-a-serverless-index).


# Limitations of querying by ID
Source: https://docs.pinecone.io/troubleshooting/limitations-of-querying-by-id

Understand why querying by record ID can omit that ID under ANN search, and when to use fetch or metadata filters to retrieve a specific vector reliably.

When [querying by record ID](/guides/search/semantic-search#search-with-a-record-id), even with a high `topK`, the response is not guaranteed to include the record with the specified ID.

## Approximate nearest neighbor (ANN)

Approximate nearest neighbor algorithms are designed to quickly find the closest matches to a given data point within large datasets with reasonable accuracy rather than perfect precision. Depending on the data, ANN may have a slightly lower accuracy than Known Nearest Neighbor (KNN) algorithms, but will have significantly lower read costs and latency than KNN. This is one of the key features of ANN.

ANN algorithms assess broad data clusters to find matches. Some of these clusters might be ignored even if they contain relevant records simply because their overall similarity to the query is lower, because the algorithm aims to optimize the search by focusing on areas with a higher density of potential matches.

See our learning center for more information on [ANN algorithms](https://www.pinecone.io/learn/a-developers-guide-to-ann-algorithms/).

## Recommendations

### Perform a fetch instead of a query

Results from [Fetch](/guides/manage-data/fetch-data) are guaranteed to include the record with the specified ID.

### Use metadata filtering

A [metadata filter](/guides/index-data/indexing-overview#metadata) in an ANN search effectively narrows the dataset to a more relevant subset, fine-tuning the search process. By explicitly excluding less relevant clusters from the outset, the search is performed among a group of records more closely related to the query, thereby increasing the efficiency and accuracy of the search.


# Login code issues
Source: https://docs.pinecone.io/troubleshooting/login-code-issues

Troubleshoot “Login code issues” in Pinecone: If the email token you received from Pinecone is not accepted when logging in there may be a few different.

If the email token you received from Pinecone is not accepted when logging in there may be a few different reasons why:

## The code has expired

A code is only valid for 10 hours, so if you enter it after that time it will no longer be accepted.

## The code has already been used

If you're using a shared email account or distribution list, please check with your teammates to see if anyone else has used your code.

## A subsequent request was made

Similar to the first reason, if you're using a shared account, it's possible that someone else requested a code after you did, rendering the first code invalid.

## Your computer's system clock time is offset

User authentication with a verification code relies on your device’s system clock to verify the time. If your computer’s clock is more than 10 minutes off from your time zone, the login will fail. If you see the below error message, please set your system clock to the correct time and time zone before trying again.

```
Please check your computer's system clock time. See https://docs.pinecone.io/troubleshooting/login-code-issues for more information.
```

## Your anti-spam filter followed the links in the email to check their validity

If your anti-spam filter followed the links in the email to check their validity, and one of them submitted the code as part of the URL, please check with your anti-spam system admin or vendor to see if this might be the cause.


# Python AttributeError: module pinecone has no attribute init
Source: https://docs.pinecone.io/troubleshooting/module-pinecone-has-no-attribute-init

Troubleshoot “Python AttributeError: module pinecone has no attribute init” in Pinecone: If you are using Pinecone serverless and getting the error , first.

## Problem

If you are using Pinecone serverless and getting the error `"AttributeError: module 'pinecone' has no attribute 'init'`, first check that you are using the latest version of the Python SDK.

You can check the version of the client by running:

```shell theme={null}
pip show pinecone
```

## Solution

Serverless requires a minimum version of 3.0. To upgrade to the latest version, run:

```shell theme={null}
# If you're interacting with Pinecone via HTTP:
pip install pinecone --upgrade

# If you're using gRPC:
# pip install "pinecone[grpc]" --upgrade
```

If you're on the right version and getting this error, you just have to make some slight changes to your code to make use of serverless. Instead of calling:

```python theme={null}
import pinecone

pinecone.init(api_key=api_key,environment=environment)
```

Use the following if you're interacting with Pinecone via HTTP requests:

```python theme={null}
from pinecone import Pinecone

pc = Pinecone(api_key=api_key)
```

Or, use the following if you're using gRPC:

```python theme={null}
from pinecone.grpc import PineconeGRPC as Pinecone

pc = Pinecone(api_key=api_key)
```

You no longer need to specify the cloud environment your index is hosted in; the API key is all you need.


# Node.js Troubleshooting
Source: https://docs.pinecone.io/troubleshooting/nodejs-troubleshooting

Troubleshoot Pinecone Node.js SDK issues that work locally but fail in deployment, including environment, network, and serverless runtime configuration.

There could be several reasons why a [Node.js application](/reference/sdks/node/overview) works in development mode but not in deployment.

In order to troubleshoot the issue, it's important to identify where the application is failing and compare the development and deployment environments to see what differences exist. It's also important to review any error messages or logs that are generated to help identify the issue.

You may also reach out to our [community of Pinecone users](https://community.pinecone.io) for help.

Here are a few aspects to troubleshoot:

## Dependency version mismatch

Sometimes, different environments have different versions of dependencies installed. If the application was developed using a specific version of a dependency, and that version is not installed on the deployment environment, the application may not work as expected.

## Environment configuration

The development environment may have different configurations from the deployment environment. For example, the development environment may have different environment variables set or different network settings. If the application relies on specific configuration settings that are not present in the deployment environment, it may not work.

## Permissions

The application may require permissions to access certain resources that are only granted in the development environment. For example, if the application needs to write to a specific directory, the permissions to write to that directory may only be granted in the development environment.

## Database connection

If the application relies on a database connection, it's possible that the connection settings are different in the deployment environment. For example, the database may have a different hostname or port number.

## Code optimization

During development, the application may have been running on a development server that did not optimize the code. However, when deployed, the application may be running on a production server that is optimized for performance. If there are code issues or performance bottlenecks, they may only appear when the application is deployed.

## Install fetch

It may be necessary to install the `fetch` Python library for compatibility with node.js.


# PineconeAttribute errors with LangChain
Source: https://docs.pinecone.io/troubleshooting/pinecone-attribute-errors-with-langchain

Resolve PineconeAttribute errors in LangChain caused by outdated packages by upgrading langchain-pinecone and the Pinecone Python SDK to current releases.

## Problem

When using an outdated version of LangChain, you may encounter errors like the following:

```console theme={null}
Pinecone has no attribute 'from_texts'
```

```console theme={null}
Pinecone has no attribute `from_documents'
```

## Solution

Previously, the Python classes for both LangChain and Pinecone had objects named `Pinecone`, but this is no longer an issue in the latest LangChain version. To resolve these errors, upgrade LangChain to >=0.0.3:

```shell theme={null}
pip install --upgrade langchain-pinecone
```

Depending on which version of LangChain you are upgrading from, you may need to update your code. You can find more information about using LangChain with Pinecone in our [documentation](/integrations/langchain#4-initialize-a-langchain-vector-store).


# Pinecone Support SLAs
Source: https://docs.pinecone.io/troubleshooting/pinecone-support-slas

Troubleshoot “Pinecone Support SLAs” in Pinecone: New first-response SLAs went into effect on September 16th, 2024. See the pricing page for more details.

<Note>
  New first-response SLAs went into effect on September 16th, 2024. See the [pricing page](https://www.pinecone.io/pricing/?plans=support) for more details.
</Note>

Pinecone Support has first-response SLAs based on the support plan of the ticket requester's organization and the selected severity. These SLAs are as follows:

### Premium

* **Sev-1**: 30 minutes
* **Sev-2**: 2 business hours
* **Sev-3**: 8 business hours
* **Sev-4**: 12 business hours

### Pro

* **Sev-1**: 2 hours
* **Sev-2**: 4 business hours
* **Sev-3**: 12 business hours
* **Sev-4**: 2 business days

### Developer

* **Sev-1**: 8 business hours
* **Sev-2**: 12 business hours
* **Sev-3**: 2 business days
* **Sev-4**: 3 business days

The current business hours for Pinecone Support are 8 AM to 8 PM Eastern Time. SLAs only apply outside of our business hours for Sev-1 tickets created by users subscribed to Pro or Premium support. All first-response SLAs only apply to tickets created by users in an organization subscribed to a [support plan](https://www.pinecone.io/pricing/?plans=support).

Pinecone Support is reserved for customers on the Standard billing plan. However, you may find helpful resources on our [community page](https://community.pinecone.io). This is a great place to ask questions and find answers from other Pinecone users and our community moderators.


# Restrictions on index names
Source: https://docs.pinecone.io/troubleshooting/restrictions-on-index-names

Troubleshoot “Restrictions on index names” in Pinecone: There are two main restrictions on index names in Pinecone: character restrictions and a maximum.

There are two main restrictions on index names in Pinecone: **character restrictions** and a **maximum length**.

## Character restrictions

Index names can only use UTF-8 lowercase alphanumeric Latin characters and dashes. Non-Latin characters (such as Chinese or Cyrillic) and emojis are not supported. Additionally, they cannot contain dots, as these are used to separate hosts and subnets in DNS, which Pinecone uses to route requests and queries.

## Maximum length

The maximum length of your index name is a factor of limits imposed by the infrastructure Pinecone uses behind the scenes. The combination of your index name and project ID (normally a seven-character, alphanumeric string) cannot exceed 52 characters, plus a dash to separate them. Your project ID is different from your project name, which is often longer than seven characters. You can identify your project ID by the hostname used to connect to your index; it's the last set of characters after the final `-`. For example, if your index is `foo` and your project ID is `abc1234` in the `us-east1-gcp` environment, your index's hostname would be `foo-abc1234.svc.us-east1-gcp.pinecone.io`, and its length would be 11 characters (3 for the index name, 1 for the dash, 7 for the project ID).


# Return all vectors in an index
Source: https://docs.pinecone.io/troubleshooting/return-all-vectors-in-an-index

Troubleshoot “Return all vectors in an index” in Pinecone: Pinecone is designed to find vectors that are similar to a given set of conditions, either by.

Pinecone is designed to find vectors that are similar to a given set of conditions, either by comparing a new vector to the ones in the index or by comparing a vector in the index to all of the others using the [query by ID feature](/reference/api/2024-10/data-plane/query). Because the Pinecone query function relies on performing this similarity search, there isn't a way to return all of the vectors currently stored in the index with a single query.

There isn't a guaranteed workaround for this type of query today but providing the ability to query all or export the entire index is on our roadmap for the future.


# Serverless index connection errors
Source: https://docs.pinecone.io/troubleshooting/serverless-index-connection-errors

Troubleshoot “Serverless index connection errors” in Pinecone: To connect to a serverless index, you must use an updated Pinecone client. Trying to connect.

## Problem

To connect to a serverless index, you must use an updated Pinecone client. Trying to connect to a serverless index with an outdated client will raise errors similar to one of the following:

```console console theme={null}
Failed to resolve 'controller.us-west-2.pinecone.io'

controller.us-west-2-aws.pinecone.io not found

Request failed to reach Pinecone while calling https://controller.us-west-2.pinecone.io/actions/whoami
```

## Solution

Upgrade to the latest [Python](https://github.com/pinecone-io/pinecone-python-client) or [Node.js](https://sdk.pinecone.io/typescript/) client and try again:

<CodeGroup>
  ```python Python theme={null}
  pip install "pinecone[grpc]" --upgrade
  ```

  ```js JavaScript theme={null}
  npm install @pinecone-database/pinecone@latest
  ```
</CodeGroup>


# Unable to pip install
Source: https://docs.pinecone.io/troubleshooting/unable-to-pip-install

Resolve install issues for the Pinecone Python SDK: pick the right Python 3.x command, install pinecone or pinecone with gRPC, and upgrade to the latest.

Python `3.x` uses `pip3`. Use the following commands in your terminal to install the latest version of the [Pinecone Python SDK](/reference/sdks/python/overview):

```Shell Shell theme={null}
# If you are connecting to Pinecone via gRPC:
pip3 install -U pinecone[grpc]
```

```Shell Shell theme={null}
# If you are connecting to Pinecone via HTTP:
pip3 install -U pinecone
```


# Wait for index creation to be complete
Source: https://docs.pinecone.io/troubleshooting/wait-for-index-creation

Wait for Pinecone index creation to finish using describe_index polling in the Python SDK before upserting to avoid 403 or 404 errors.

Pinecone index creation involves several different subsystems, including one which accepts the job of creating the index and one that actually performs the action. The Python SDK and the REST API are designed to interact with the first system during index creation but not the second.

This means that when a request call to [`create_index()`](/reference/api/latest/control-plane/create_index) is made, what's actually happening is that the job is being submitted to the queue to be completed. We do it this way for several reasons, including enforcing separation between the control and data planes.

If you need your application to wait for the index to be created before continuing to its next step, there is a way to ensure this happens, though. [`describe_index()`](/reference/api/latest/control-plane/describe_index) returns data about the state of the index, including whether it is ready to accept data. You simply call that method until it returns a 200 status code and the status object reports that the index is ready. Because the return is a tuple, we just have to access the slice containing the status object and check the boolean state of the ready variable. This is one possible method of doing so using the Python SDK:

```python theme={null}
import pinecone
from time import sleep

def wait_on_index(index: str):
  """
  Takes the name of the index to wait for and blocks until it's available and ready.
  """
  ready = False
  while not ready:
    try:
      desc = pinecone.describe_index(index)
      if desc[7]['ready']:
        return True
    except pinecone.core.client.exceptions.NotFoundException:
      # NotFoundException means the index is created yet.
      pass
    sleep(5)
```

Calling `wait_on_index()` would then allow your application to only continue to upsert data once the index is fully online and available to accept data, avoiding potential 403 or 404 errors.


# Create a project
Source: https://docs.pinecone.io/guides/assistant/admin/create-a-project

Create a new Pinecone project in the console or through the Admin API, add tags, and optionally enable a customer-managed encryption key (CMEK).

This page shows you how to create a project.

If you are an [organization owner or organization manager](/guides/assistant/admin/organizations-overview#organization-roles), you can create a project in your organization:

<Tabs>
  <Tab title="Pinecone console">
    1. In the Pinecone console, go to [**your profile > Organization settings > Projects**](https://app.pinecone.io/organizations/-/settings/projects).

    2. Click **+ Create Project**.

    3. Enter a **Name**.

       <Note>
         A project name can contain up to 512 characters. For more information, see [Object identifiers](/reference/api/database-limits#identifier-limits).
       </Note>

    4. (Optional) Tags are key-value pairs that you can use to categorize and identify the project. To add a tag, click **+ Add tag** and enter a tag key and value.

    5. (Optional) Select **Encrypt with Customer Managed Encryption Key**. For more information, see [Configure CMEK](/guides/production/configure-cmek).

    6. Click **Create project**.

       To load an index with a [sample dataset](/guides/data/use-sample-datasets), click **Load sample data** and follow the prompts.

    <Note>
      The number of projects per organization varies by plan—see [Projects per organization](/reference/api/database-limits#projects-per-organization). To create additional projects, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan).
    </Note>
  </Tab>

  <Tab title="Code">
    <Note>
      An [access token](/guides/assistant/admin/manage-organization-service-accounts#retrieve-an-access-token) must be provided to complete this action through the Admin API. The Admin API is in [public preview](/assistant-release-notes/feature-availability).
    </Note>

    <CodeGroup>
      ```bash curl theme={null}
      PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

      curl "https://api.pinecone.io/admin/projects" \
          -H "X-Pinecone-Api-Version: 2025-10" \
      	-H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
      	-d '{
                "name":"example-project"
              }'
      ```

      ```bash CLI theme={null}
      # Target the organization for which you want to 
      # create a project.
      pc target -o "example-org"
      # Create the project and set it as the target 
      # project for the CLI.
      pc project create -n "example-project" --target
      ```
    </CodeGroup>

    The example returns a response like the following:

    <CodeGroup>
      ```json curl theme={null}
      {
        "id": "32c8235a-5220-4a80-a9f1-69c24109e6f2",
        "name": "example-project",
        "max_pods": 0,
        "force_encryption_with_cmek": false,
        "organization_id": "-NM7af6f234168c4e44a",
        "created_at": "2025-03-16T22:46:45.030Z"
      }
      ```

      ```text CLI theme={null}
      [SUCCESS] Project example-cli-project created successfully.

      ATTRIBUTE           VALUE
      Name                example-project
      ID                  32c8235a-5220-4a80-a9f1-69c24109e6f2
      Organization ID     -NM7af6f234168c4e44a
      Created At          2025-10-27 23:27:46.370088 +0000 UTC
      Force Encryption    false
      Max Pods            5

      [SUCCESS] Target project set to example-cli-project
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Next steps

* [Add users to your project](/guides/assistant/admin/manage-project-members#add-members-to-a-project)
* [Create an assistant](/guides/assistant/create-assistant)


# Manage API keys
Source: https://docs.pinecone.io/guides/assistant/admin/manage-api-keys

Create, view, update, and delete Pinecone API keys for a project, plus assign custom permission roles to control data plane and control plane access.

Each Pinecone [project](/guides/assistant/admin/projects-overview) has one or more API keys. In order to [make calls to the Pinecone API](/guides/assistant/quickstart/sdk-quickstart), you must provide a valid API key for the relevant Pinecone project.

This page shows you how to [create](#create-an-api-key), [view](#view-project-api-keys), [update](#update-an-api-key), and [delete](#delete-an-api-key) API keys.

<Warning>
  If you use custom API key permissions, ensure that you [target your index by host](/guides/manage-data/target-an-index#target-by-index-host-recommended) when performing data operations such as `upsert` and `query`.
</Warning>

## Create an API key

You can create a new API key for your project, as follows:

<Tabs>
  <Tab title="Pinecone console">
    1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects).

    2. Select your project.

    3. Go to **API keys**.

    4. Click **Create API key**.

    5. Enter an **API key name**.

    6. Select the **Permissions** to grant to the API key. For a description of the permission roles, see [Project roles](/guides/assistant/admin/projects-overview#project-roles).

       <Note>
         Users on the Starter and Builder plans can set the permissions to **All** only. To customize the permissions further, [upgrade to the Standard or Enterprise plan](/guides/organizations/manage-billing/upgrade-billing-plan).
       </Note>

    7. Click **Create key**.

    8. Copy and save the generated API key in a secure place for future use.

       <Warning>
         You will not be able to see the API key again after you close the dialog.
       </Warning>

    9. Click **Close**.
  </Tab>

  <Tab title="Code">
    <Note>
      An [access token](/guides/assistant/admin/manage-organization-service-accounts#retrieve-an-access-token) must be provided to complete this action through the Admin API. The Admin API is in [public preview](/assistant-release-notes/feature-availability).
    </Note>

    <CodeGroup>
      ```bash curl theme={null}
      PINECONE_PROJECT_ID="YOUR_PROJECT_ID"
      PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

      curl -X POST "https://api.pinecone.io/admin/projects/$PINECONE_PROJECT_ID/api-keys" \
           -H "X-Pinecone-Api-Version: 2025-10" \
           -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
           -d '{
                 "name": "example-api-key",
                 "roles": ["ProjectEditor"]
               }'
      ```

      ```bash CLI theme={null}
      # Target the project for which you want to create an API key.
      pc target -o "example-org" -p "example-project"
      # Create the API key
      pc api-key create -n "example-api-key" --roles ProjectEditor
      ```
    </CodeGroup>

    The example returns a response like the following:

    <CodeGroup>
      ```json curl theme={null}
      {
        "key": {
          "id": "62b0dbfe-3489-4b79-b850-34d911527c88",
          "name": "example-api-key",
          "project_id": "32c8235a-5220-4a80-a9f1-69c24109e6f2",
          "roles": [
            "ProjectEditor"
          ],
          "created_at": "2025-10-20T23:40:27.069075Z"
        },
        "value": "..."
      }
      ```

      ```text CLI theme={null}
      ATTRIBUTE     VALUE
      Name          example-api-key
      ID            62b0dbfe-3489-4b79-b850-34d911527c88
      Value         ...
      Project ID    32c8235a-5220-4a80-a9f1-69c24109e6f2
      Roles         ProjectEditor
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## View project API keys

You can [view the API keys](/reference/api/latest/admin/list_api_keys) for your project:

<Tabs>
  <Tab title="Pinecone console">
    1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects).
    2. Select your project.
    3. Go to the **API keys** tab.

    You will see a list of all API keys for the project, including their names, IDs, and permissions.
  </Tab>

  <Tab title="Code">
    <Note>
      An [access token](/guides/assistant/admin/manage-organization-service-accounts#retrieve-an-access-token) must be provided to complete this action through the Admin API. The Admin API is in [public preview](/assistant-release-notes/feature-availability).
    </Note>

    <CodeGroup>
      ```bash curl theme={null}
      PINECONE_PROJECT_ID="32c8235a-5220-4a80-a9f1-69c24109e6f2"
      PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

      curl -X GET "https://api.pinecone.io/admin/projects/$PINECONE_PROJECT_ID/api-keys" \
           -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
           -H "X-Pinecone-Api-Version: 2025-10"
      ```

      ```bash CLI theme={null}
      PINECONE_PROJECT_ID="32c8235a-5220-4a80-a9f1-69c24109e6f2"

      pc api-key list -i $PINECONE_PROJECT_ID
      ```
    </CodeGroup>

    The example returns a response like the following:

    <CodeGroup>
      ```json curl theme={null}
      {
        "data": [
          {
            "id": "62b0dbfe-3489-4b79-b850-34d911527c88",
            "name": "example-api-key",
            "project_id": "32c8235a-5220-4a80-a9f1-69c24109e6f2",
            "roles": [
              "ProjectEditor"
            ],
            "created_at": "2025-10-20T23:39:43.665754Z"
          },
          {
            "id": "0d0d3678-81b4-4e0d-a4f0-70ba488acfb7",
            "name": "example-api-key-2",
            "project_id": "32c8235a-5220-4a80-a9f1-69c24109e6f2",
            "roles": [
              "ProjectEditor"
            ],
            "created_at": "2025-10-20T23:43:13.176422Z"
          }
        ]
      }
      ```

      ```text CLI theme={null}
      Organization: example-organization (ID: -NM7af6f234168c4e44a)
      Project: example-project (ID: 32c8235a-5220-4a80-a9f1-69c24109e6f2)

      API Keys

      NAME                 ID                                      PROJECT ID                              ROLES
      example-api-key      62b0dbfe-3489-4b79-b850-34d911527c88    32c8235a-5220-4a80-a9f1-69c24109e6f2    ProjectEditor
      example-api-key-2    0d0d3678-81b4-4e0d-a4f0-70ba488acfb7    32c8235a-5220-4a80-a9f1-69c24109e6f2    ProjectEditor
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## View API key details

You can [view the details of an API key](/reference/api/latest/admin/fetch_api_key):

<Tabs>
  <Tab title="Pinecone console">
    1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects).
    2. Select your project.
    3. Go to the **API keys** tab.
    4. In the row of the API key you want to change, in the **Actions** column, click **ellipsis (...) menu > Settings**.

    You will see the API key's name, ID, and permissions.
  </Tab>

  <Tab title="Code">
    <Note>
      An [access token](/guides/assistant/admin/manage-organization-service-accounts#retrieve-an-access-token) must be provided to complete this action through the Admin API. The Admin API is in [public preview](/assistant-release-notes/feature-availability).
    </Note>

    <CodeGroup>
      ```bash curl theme={null}
      PINECONE_API_KEY_ID="62b0dbfe-3489-4b79-b850-34d911527c88"
      PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

      curl -X GET "https://api.pinecone.io/admin/api-keys/$PINECONE_API_KEY_ID" \
           -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
           -H "accept: application/json" \
           -H "X-Pinecone-Api-Version: 2025-10"
      ```

      ```bash CLI theme={null}
      PINECONE_API_KEY_ID="62b0dbfe-3489-4b79-b850-34d911527c88"

      pc api-key describe -i $PINECONE_API_KEY_ID
      ```
    </CodeGroup>

    The example returns a response like the following:

    <CodeGroup>
      ```json curl theme={null}
      {
        "id": "62b0dbfe-3489-4b79-b850-34d911527c88",
        "name": "example-api-key",
        "project_id": "32c8235a-5220-4a80-a9f1-69c24109e6f2",
        "roles": [
          "ProjectEditor"
        ],
        "created_at": "2025-10-22T19:27:21.202955Z"
      }
      ```

      ```text CLI theme={null}
      ATTRIBUTE     VALUE
      Name          example-api-key
      ID            62b0dbfe-3489-4b79-b850-34d911527c88
      Project ID    32c8235a-5220-4a80-a9f1-69c24109e6f2
      Roles         ProjectEditor
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Update an API key

<Note>
  Users on the Starter and Builder plans cannot change API key permissions once they are set. Instead, [create a new API key](#create-an-api-key) or [upgrade to the Standard or Enterprise plan](/guides/organizations/manage-billing/upgrade-billing-plan).
</Note>

If you are a [project owner](/guides/assistant/admin/projects-overview#project-roles), you can update the name and roles of an API key:

<Tabs>
  <Tab title="Pinecone console">
    1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects).

    2. Select your project.

    3. Go to the **API keys** tab.

    4. In the row of the API key you want to change, in the **Actions** column, click **ellipsis (...) menu > Settings**.

    5. Change the name and/or permissions for the API key as needed.

       For information about the different API key permissions, refer to [Project roles](/guides/assistant/admin/projects-overview#project-roles).

    6. Click **Update**.
  </Tab>

  <Tab title="Code">
    <Note>
      An [access token](/guides/assistant/admin/manage-organization-service-accounts#retrieve-an-access-token) must be provided to complete this action through the Admin API. The Admin API is in [public preview](/assistant-release-notes/feature-availability).
    </Note>

    <CodeGroup>
      ```bash curl theme={null}
      PINECONE_API_KEY_ID="62b0dbfe-3489-4b79-b850-34d911527c88"
      PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

      curl -X PATCH "https://api.pinecone.io/admin/api-keys/$PINECONE_API_KEY_ID" \
           -H "X-Pinecone-Api-Version: 2025-10" \
           -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
           -d '{
                 "name": "new-api-key-name",
                 "roles": ["ProjectEditor"]
               }'
      ```

      ```bash CLI theme={null}
      PINECONE_API_KEY_ID="62b0dbfe-3489-4b79-b850-34d911527c88"

      # Target the organization that contains the API key.
      pc target -o "example-org"
      # Update the API key name.
      pc api-key update -i $PINECONE_API_KEY_ID -n "new-api-key-name"
      ```
    </CodeGroup>

    The example returns a response like the following:

    <CodeGroup>
      ```json curl theme={null}
      {
        "id": "62b0dbfe-3489-4b79-b850-34d911527c88",
        "name": "new-api-key-name",
        "project_id": "32c8235a-5220-4a80-a9f1-69c24109e6f2",
        "roles": [
          "ProjectEditor"
        ],
        "created_at": "2025-10-22T19:27:21.202955Z"
      }
      ```

      ```text CLI theme={null}
      ATTRIBUTE     VALUE
      Name          new-api-key-name
      ID            62b0dbfe-3489-4b79-b850-34d911527c88
      Project ID    32c8235a-5220-4a80-a9f1-69c24109e6f2
      Roles         ProjectEditor
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Delete an API key

If you are a [project owner](/guides/assistant/admin/projects-overview#project-roles), you can delete your API key:

<Tabs>
  <Tab title="Pinecone console">
    1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects).
    2. Select your project.
    3. Go to the **API keys** tab.
    4. In the row of the API key you want to change, in the **Actions** column, click **ellipsis (...) menu > Delete**.
    5. Enter the **API key name**.
    6. Click **Confirm deletion**.

       <Warning>
         Deleting an API key is irreversible and will immediately disable any applications using the API key.
       </Warning>
  </Tab>

  <Tab title="Code">
    <Note>
      An [access token](/guides/assistant/admin/manage-organization-service-accounts#retrieve-an-access-token) must be provided to complete this action through the Admin API. The Admin API is in [public preview](/assistant-release-notes/feature-availability).
    </Note>

    <CodeGroup>
      ```bash curl theme={null}
      PINECONE_API_KEY_ID="62b0dbfe-3489-4b79-b850-34d911527c88"
      PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

      curl -X DELETE "https://api.pinecone.io/admin/api-keys/$PINECONE_API_KEY_ID" \
           -H "X-Pinecone-Api-Version: 2025-10" \
           -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN"
      ```

      ```bash CLI theme={null}
      PINECONE_API_KEY_ID="62b0dbfe-3489-4b79-b850-34d911527c88"

      # Delete the API key. Use --skip-confirmation to skip
      # the confirmation prompt.
      pc api-key delete -i $PINECONE_API_KEY_ID
      ```
    </CodeGroup>

    The example returns a response like the following:

    <CodeGroup>
      ```text curl theme={null}
      No response payload
      ```

      ```text CLI theme={null}
      [WARN] This operation will delete API key example-api-key from project example-project.
      [WARN] Any integrations that authenticate with this API key will immediately stop working.
      [WARN] This action cannot be undone.
      Do you want to continue? (y/N): y
      [INFO] You chose to continue delete.
      [SUCCESS] API key example-api-key deleted
      ```
    </CodeGroup>
  </Tab>
</Tabs>


# Manage organization members
Source: https://docs.pinecone.io/guides/assistant/admin/manage-organization-members

Invite new members to your Pinecone organization, change their organization roles, and remove users to control access across all projects.

This page shows how [organization owners](/guides/assistant/admin/organizations-overview#organization-roles) can add and manage organization members.

To assign and manage roles programmatically with the Admin API, or to manage roles for service accounts and API keys, see [Manage roles and access](/guides/assistant/admin/manage-rbac).

<Tip>
  For information about managing members at the **project-level**, see [Manage project members](/guides/assistant/admin/manage-project-members).
</Tip>

## Add a member to an organization

You can add members to your organization in the [Pinecone console](https://app.pinecone.io):

1. Go to [**Settings > Access > Members**](https://app.pinecone.io/organizations/-/settings/access/members).
2. In the **Invite by email** field, enter the member's email address.
3. Choose an [**Organization role**](/guides/assistant/admin/organizations-overview#organization-roles) for the member. The role determines the member's permissions within Pinecone.
4. Click **Invite**.

When you invite a member to join your organization, Pinecone sends them an email containing a link that enables them to gain access to the organization or project. If they already have a Pinecone account, they still receive an email, but they can also immediately view the project.

## Change a member's role

You can change a member's role in the [Pinecone console](https://app.pinecone.io):

1. Go to [**Settings > Access > Members**](https://app.pinecone.io/organizations/-/settings/access/members).
2. In the row of the member whose role you want to change, click **ellipsis (...) menu > Edit role**.
3. Select an [**Organization role**](/guides/assistant/admin/organizations-overview#organization-roles) for the member.
4. Click **Edit role**.

## Remove a member

You can remove a member from your organization in the [Pinecone console](https://app.pinecone.io):

1. In the Pinecone console, go to [**Settings > Access > Members**](https://app.pinecone.io/organizations/-/settings/access/members).
2. In the row of the member you want to remove, click **ellipsis (...) menu > Remove member**.
3. Click **Remove Member**.

<Note>
  To remove yourself from an organization, click the **Leave organization** button in your user's row and confirm.
</Note>


# Manage service accounts at the organization-level
Source: https://docs.pinecone.io/guides/assistant/admin/manage-organization-service-accounts

Create and manage organization-level Pinecone service accounts, retrieve access tokens, and grant programmatic access to the Admin API.

<Note>
  This feature is in [public preview](/release-notes/feature-availability) and available only on [Enterprise plans](https://www.pinecone.io/pricing/).
</Note>

This page shows how [organization owners](/guides/assistant/admin/organizations-overview#organization-roles) can add and manage service accounts at the organization-level. Service accounts enable programmatic access to Pinecone's Admin API, which can be used to create and manage projects and API keys.

<Tip>
  Once a service account is added at the organization-level, it can be added to a project. For more information, see [Manage service accounts at the project-level](/guides/assistant/admin/manage-project-service-accounts).
</Tip>

## Create a service account

You can create a service account in the [Pinecone console](https://app.pinecone.io):

1. Go to [**Settings > Access > Service accounts**](https://app.pinecone.io/organizations/-/settings/access/service-accounts).

2. Enter a **Name** for the service account.

3. Choose an [**Organization role**](/guides/assistant/admin/organizations-overview#organization-roles) for the service account. The role determines the service account's permissions within Pinecone.

4. Click **Create**.

5. Copy and save the **Client secret** in a secure place for future use.

   <Warning>
     You will not be able to see the client secret again after you close the dialog.
   </Warning>

6. Click **Close**.

Once you have created a service account, [add it to a project](/guides/assistant/admin/manage-project-service-accounts#add-a-service-account-to-a-project) to allow it access to the project's resources.

## Retrieve an access token

To access the Admin API, you must provide an access token to authenticate. Retrieve the access token using the client secret of a service account, which was [provided at time of creation](#create-a-service-account).

You can retrieve an access token for a service account from the `https://login.pinecone.io/oauth/token` endpoint, as shown in the following example:

```bash curl theme={null}
curl "https://login.pinecone.io/oauth/token" \ # Note: Base URL is login.pinecone.io
	-H "X-Pinecone-Api-Version: 2025-10" \
	-H "Content-Type: application/json" \
	-d '{
		"grant_type": "client_credentials",
		"client_id": "YOUR_CLIENT_ID",
		"client_secret": "YOUR_CLIENT_SECRET",
		"audience": "https://api.pinecone.io/"
	}'
```

The response will include an `access_token` field, which you can use to authenticate with the Admin API.

```
{
    "access_token":"YOUR_ACCESS_TOKEN",
    "expires_in":86400,
    "token_type":"Bearer"
}
```

## Change a service account's role

You can change a service account's role in the [Pinecone console](https://app.pinecone.io):

1. Go to [**Settings > Access > Service accounts**](https://app.pinecone.io/organizations/-/settings/access/service-accounts).
2. In the row of the service account you want to update, click **ellipsis (...) menu > Manage**.
3. Select an [**Organization role**](/guides/assistant/admin/organizations-overview#organization-roles) for the service account.
4. Click **Update**.

## Update service account name

You can change a service account's name in the [Pinecone console](https://app.pinecone.io):

1. Go to [**Settings > Access > Service accounts**](https://app.pinecone.io/organizations/-/settings/access/service-accounts).
2. In the row of the service account you want to update, click **ellipsis (...) menu > Manage**.
3. Enter a new **Service account name**.
4. Click **Update**.

## Rotate a service account's secret

You can rotate a service account's client secret in the [Pinecone console](https://app.pinecone.io):

1. Go to [**Settings > Access > Service accounts**](https://app.pinecone.io/organizations/-/settings/access/service-accounts).

2. In the row of the service account you want to update, click **ellipsis (...) menu > Rotate secret**.

3. **Enter the service account name** to confirm.

4. Click **Rotate client secret**.

5. Copy and save the **Client secret** in a secure place for future use.

   <Warning>
     You will not be able to see the client secret again after you close the dialog.
   </Warning>

6. Click **Close**.

## Delete a service account

Deleting a service account will remove it from all projects and will disrupt any applications using it to access Pinecone. You delete a service account in the [Pinecone console](https://app.pinecone.io):

1. Go to [**Settings > Access > Service accounts**](https://app.pinecone.io/organizations/-/settings/access/service-accounts).
2. In the row of the service account you want to update, click **ellipsis (...) menu > Delete**.
3. **Enter the service account name** to confirm.
4. Click **Delete service account**.


# Manage project members
Source: https://docs.pinecone.io/guides/assistant/admin/manage-project-members

Add users to a Pinecone project, assign project owner or user roles, edit permissions, and remove members to control access to indexes and API keys.

[Organization owners](/guides/assistant/admin/organizations-overview#organization-roles) or [project owners](/guides/assistant/admin/projects-overview#project-roles) can manage members in a project. Each member is assigned one or more [project roles](/guides/assistant/admin/projects-overview#project-roles) that determine their permissions within the project.

To assign and manage roles programmatically with the Admin API, or to manage roles for service accounts and API keys, see [Manage roles and access](/guides/assistant/admin/manage-rbac).

<Tip>
  For information about managing members at the **organization-level**, see [Manage organization members](/guides/assistant/admin/manage-organization-members).
</Tip>

## Add members to a project

<Note>
  Project owners can add existing organization members to a project and manage their project roles. Only [organization owners](/guides/assistant/admin/organizations-overview#organization-roles) can invite people who are not yet members of the organization.
</Note>

You can add members to a project in the [Pinecone console](https://app.pinecone.io/organizations/-/projects):

1. Select your project.
2. Go to the [**Manage > Access > Members** tab](https://app.pinecone.io/organizations/-/projects/-/access/members).
3. Enter the member's email address or name.
4. Select a [**Project role**](/guides/assistant/admin/projects-overview#project-roles) for the member. The role determines the member's permissions within Pinecone.
5. Click **Invite**.

When you invite a member to join your project, Pinecone sends them an email containing a link that enables them to gain access to the project. If they already have a Pinecone account, they still receive an email, but they can also immediately view the project.

## Change a member's role

You can change a member's role in the [Pinecone console](https://app.pinecone.io/organizations/-/projects):

1. Select your project.
2. Go to the [**Manage > Access > Members** tab](https://app.pinecone.io/organizations/-/projects/-/access/members).
3. In the row of the member you want to edit, click **ellipsis (...) menu > Edit role**.
4. Select a [**Project role**](/guides/assistant/admin/projects-overview#project-roles) for the member.
5. Click **Edit role**.

## Remove a member

You can remove a member from a project in the [Pinecone console](https://app.pinecone.io/organizations/-/projects):

1. Select your project.
2. Go to the [**Manage > Access > Members** tab](https://app.pinecone.io/organizations/-/projects/-/access/members).
3. In the row of the member you want to remove, click **ellipsis (...) menu > Remove member**.
4. Click **Remove member**.

<Note>
  To remove yourself from a project, click the **Leave project** button in your user's row and confirm.
</Note>


# Manage service accounts at the project-level
Source: https://docs.pinecone.io/guides/assistant/admin/manage-project-service-accounts

Add and manage project-level service accounts in Pinecone Assistant to enable programmatic Admin API access, roles, and permissions.

<Note>
  This feature is in [public preview](/release-notes/feature-availability) and available only on [Enterprise plans](https://www.pinecone.io/pricing/).
</Note>

This page shows how [organization owners](/guides/assistant/admin/organizations-overview#organization-roles) and [project owners](/guides/assistant/admin/projects-overview#project-roles) can add and manage service accounts at the project-level. Service accounts enable programmatic access to Pinecone's Admin API, which can be used to create and manage projects and API keys.

## Add a service account to a project

After a service account has been [added to an organization](/guides/assistant/admin/manage-organization-service-accounts#create-a-service-account), it can be added to a project in the [Pinecone console](https://app.pinecone.io/organizations/-/projects):

1. Select your project.
2. Go to the [**Manage > Access > Service accounts** tab](https://app.pinecone.io/organizations/-/projects/-/access/service-accounts).
3. Select the service account to add.
4. Select a [**Project role**](/guides/assistant/admin/projects-overview#project-roles) for the service account. The role determines its permissions within Pinecone.
5. Click **Connect**.

## Change project role

To change a service account's role in the [Pinecone console](https://app.pinecone.io/organizations/-/projects):

1. Select your project.
2. Go to the [**Manage > Access > Service accounts** tab](https://app.pinecone.io/organizations/-/projects/-/access/service-accounts).
3. In the row of the service account you want to edit, click **ellipsis (...) menu > Edit role**.
4. Select a [**Project role**](/guides/projects/understanding-projects#project-roles) for the service account.
5. Click **Edit role**.

## Remove a service account from a project

To remove a service account from a project in the [Pinecone console](https://app.pinecone.io/organizations/-/projects):

1. Select your project.
2. Go to the [**Manage > Access > Service accounts** tab](https://app.pinecone.io/organizations/-/projects/-/access/service-accounts).
3. In the row of the service account you want to remove, click **ellipsis (...) menu > Disconnect**.
4. Enter the service account name to confirm.
5. Click **Disconnect**.


# Manage projects
Source: https://docs.pinecone.io/guides/assistant/admin/manage-projects

View project details, rename projects, add project tags, and delete Pinecone projects using the console or the Admin API with an access token.

This page shows you how to view project details, rename a project, and delete a project.

<Note>
  You must be an [organization owner](/guides/assistant/admin/organizations-overview#organization-roles) or [project owner](/guides/assistant/admin/projects-overview#project-roles) to edit project details or delete a project.
</Note>

## View project details

You can view the details of a project, as in the following example:

<Note>
  An [access token](/guides/assistant/admin/manage-organization-service-accounts#retrieve-an-access-token) must be provided to complete this action through the Admin API. The Admin API is in [public preview](/assistant-release-notes/feature-availability).
</Note>

<CodeGroup>
  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
  PROJECT_ID="32c8235a-5220-4a80-a9f1-69c24109e6f2"

  curl -X GET "https://api.pinecone.io/admin/projects/$PROJECT_ID" \
       -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
       -H "X-Pinecone-Api-Version: 2025-10" \
       -H "accept: application/json"
  ```

  ```bash CLI theme={null}
  PROJECT_ID="32c8235a-5220-4a80-a9f1-69c24109e6f2"

  # Target the organization that contains the project.
  pc target -o "example-org" 
  # Fetch the project details.
  pc project describe -i $PROJECT_ID
  ```
</CodeGroup>

The example returns a response like the following:

<CodeGroup>
  ```json curl theme={null}
  {
    "id": "32c8235a-5220-4a80-a9f1-69c24109e6f2",
    "name": "example-project",
    "max_pods": 5,
    "force_encryption_with_cmek": false,
    "organization_id": "-NM7af6f234168c4e44a",
    "created_at": "2025-10-27T23:27:46.370088Z"
  }
  ```

  ```text CLI theme={null}
  ATTRIBUTE           VALUE
  Name                example-project
  ID                  32c8235a-5220-4a80-a9f1-69c24109e6f2
  Organization ID     -NM7af6f234168c4e44a
  Created At          2025-10-27 23:27:46.370088 +0000 UTC
  Force Encryption    false
  Max Pods            5
  ```
</CodeGroup>

<Tip>
  You can view project details using the [Pinecone console](https://app.pinecone.io/organizations/-/settings/projects/-/indexes).
</Tip>

## Rename a project

You can change the name of your project:

<Tabs>
  <Tab title="Pinecone console">
    1. In the Pinecone console, go to [**Settings > Projects**](https://app.pinecone.io/organizations/-/settings/projects).

    2. Click the **ellipsis (...) menu > Configure** icon next to the project you want to update.

    3. Enter a new **Project Name**.

       <Note>
         A project name can contain up to 512 characters.
       </Note>

    4. Click **Save Changes**.
  </Tab>

  <Tab title="Code">
    <Note>
      An [access token](/guides/assistant/admin/manage-organization-service-accounts#retrieve-an-access-token) must be provided to complete this action through the Admin API. The Admin API is in [public preview](/assistant-release-notes/feature-availability).
    </Note>

    <CodeGroup>
      ```bash curl theme={null}
      PROJECT_ID="YOUR_PROJECT_ID"
      PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

      curl -X PATCH "https://api.pinecone.io/admin/projects/$PROJECT_ID" \
           -H "accept: application/json" \
           -H "Content-Type: application/json" \
           -H "X-Pinecone-Api-Version: 2025-10" \
           -d '{
                 "name": "updated-example-project"
               }'
      ```

      ```bash CLI theme={null}
      PROJECT_ID="YOUR_PROJECT_ID"

      # Target the project to update.
      pc target -o "example-org" "example-project"
      # Update the project name.
      pc project update -i $PROJECT_ID -n "updated-example-project"
      ```
    </CodeGroup>

    The example returns a response like the following:

    <CodeGroup>
      ```json curl theme={null}
      {
        "id": "32c8235a-5220-4a80-a9f1-69c24109e6f2",
        "name": "updated-example-project",
        "max_pods": 5,
        "force_encryption_with_cmek": false,
        "organization_id": "-NM7af6f234168c4e44a",
        "created_at": "2025-10-27T23:27:46.370088Z"
      }
      ```

      ```text CLI theme={null}
      [SUCCESS] Project 32c8235a-5220-4a80-a9f1-69c24109e6f2 updated successfully.
      ATTRIBUTE           VALUE
      Name                updated-example-project
      ID                  32c8235a-5220-4a80-a9f1-69c24109e6f2
      Organization ID     -NM7af6f234168c4e44a
      Created At          2025-10-27 23:27:46.370088 +0000 UTC
      Force Encryption    false
      Max Pods            5
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Add project tags

Project tags are key-value pairs that you can use to categorize and identify a project.

To add project tags, use the Pinecone console.

1. In the Pinecone console, go to [**Settings > Projects**](https://app.pinecone.io/organizations/-/settings/projects).
2. Click the **ellipsis (...) menu > Configure** icon next to the project you want to update.
3. Click **+ Add tag** and enter a tag key and value. Repeat for each tag you want to add.
4. Click **Save Changes**.

<Tip>
  You can also [add tags to indexes](/guides/manage-data/manage-indexes#configure-index-tags).
</Tip>

## Delete a project

To delete a project, you must first [delete all data](/guides/manage-data/delete-data), [indexes](/guides/manage-data/manage-indexes#delete-an-index), [collections](/guides/indexes/pods/back-up-a-pod-based-index#delete-a-collection), [backups](/guides/manage-data/back-up-an-index#delete-a-backup) and [assistants](/guides/assistant/manage-assistants#delete-an-assistant) associated with the project. Then, you can delete the project itself:

<Tabs>
  <Tab title="Pinecone console">
    1. In the Pinecone console, go to [**Settings > Projects**](https://app.pinecone.io/organizations/-/settings/projects).
    2. For the project you want to delete, click the **ellipsis (...) menu > Delete**.
    3. Enter the project name to confirm the deletion.
    4. Click **Delete Project**.
  </Tab>

  <Tab title="Code">
    <Note>
      An [access token](/guides/assistant/admin/manage-organization-service-accounts#retrieve-an-access-token) must be provided to complete this action through the Admin API. The Admin API is in [public preview](/assistant-release-notes/feature-availability).
    </Note>

    <CodeGroup>
      ```bash curl theme={null}
      PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
      PROJECT_ID="32c8235a-5220-4a80-a9f1-69c24109e6f2"

      curl -X DELETE "https://api.pinecone.io/admin/projects/$PROJECT_ID" \
           -H "X-Pinecone-Api-Version: 2025-10" \
           -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN"
      ```

      ```bash CLI theme={null}
      PINECONE_PROJECT_ID="32c8235a-5220-4a80-a9f1-69c24109e6f2"

      # Target the organization that contains the project.
      pc target -o "example-org" 
      # Delete the project. Use --skip-confirmation to skip 
      # the confirmation prompt.
      pc project delete -i $PINECONE_PROJECT_ID
      ```
    </CodeGroup>
  </Tab>
</Tabs>


# Monitor usage and cost
Source: https://docs.pinecone.io/guides/assistant/admin/monitor-spend-and-usage

Monitor Pinecone Assistant usage and cost, set monthly spend alerts, and track token usage across chat, context retrieval, and evaluation.

## Set monthly spend alerts

You can set up email alerts to monitor your organization's monthly spending. These alerts notify designated recipients when spending reaches specified thresholds. The alerts automatically reset at the start of each monthly billing cycle.

<Note>
  Spend alerts are available on the [Standard and Enterprise plans](https://www.pinecone.io/pricing/). They are not needed on the Starter or Builder plans, where usage is capped by plan quotas rather than billed per unit.
</Note>

To set a spend alert:

1. Go to [Settings > Spend alerts](https://app.pinecone.io/organizations/-/settings/spend-alerts) in the Pinecone console
2. Click **+ Add Alert**.
3. Enter the dollar amount for the spend alert.
4. Enter the email addresses to send the alert to. [Organization owners](/guides/organizations/understanding-organizations#organization-roles) are listed by default.
5. Click **Create**.

To edit a spend alert:

1. In the row of the spend alert you want to edit, click **ellipsis (...) menu > Edit**.
2. Change the dollar amount and/or email addresses for the spend alert.
3. Click **Update**.

<Note>
  **Auto-spend spike alert**: To protect from unexpected cost increases, Pinecone sends an alert when spending exceeds double your previous month's invoice amount. While the alert threshold is fixed and the alert cannot be deleted, you can modify which email addresses receive the alert and enable or disable the alert notifications.
</Note>

## Monitor organization-level usage

<Note>
  You must be an [organization owner or billing admin](/guides/assistant/admin/organizations-overview#organization-roles) to view usage across your Pinecone organization. Also, this feature is available only to organizations on the Standard or Enterprise plans.
</Note>

To view and download a report of your usage and costs for your Pinecone organization, go to [**Settings > Usage**](https://app.pinecone.io/organizations/-/settings/usage) in the Pinecone console.

All dates are given in UTC to match billing invoices.

## Monitor token usage

Requests to the [chat](/reference/api/latest/assistant/chat_assistant), [context retrieval](/reference/api/latest/assistant/context_assistant), and [evaluation](/reference/api/latest/assistant/metrics_alignment) API endpoints return a `usage` parameter with `prompt_tokens`, `completion_tokens`, and `total_tokens` generated.

<Tabs>
  <Tab title="Chat">
    For [chat](/guides/assistant/chat-with-assistant), tokens are defined as follows:

    * `prompt_tokens` are based on the messages sent to the assistant and the context snippets retrieved from the assistant and sent to a model. Messages sent to the assistant can include messages from the [chat history](/guides/assistant/chat-with-assistant#provide-conversation-history) in addition to the newest message.

      `prompt_tokens` appear as **Assistants Input Tokens** on invoices.
    * `completion_tokens` are based on the answer from the model.

      `completion_tokens` appear as **Assistants Output Tokens** on invoices.
    * `total_tokens` is the sum of `prompt_tokens` and `completion_tokens`.

    ```json Example chat response {9-13} theme={null}
    {
        "finish_reason": "stop",
        "message": {
            "role": "assistant",
            "content": "The Chief Financial Officer (CFO) of Netflix is Spencer Neumann."
        },
        "id": "000000000000000030513193ccc52814",
        "model": "gpt-4o-2024-11-20",
        "usage": {
            "prompt_tokens": 23626,
            "completion_tokens": 21,
            "total_tokens": 23647
        },
        "citations": [
            {
                "position": 63,
                "references": [
                    {
                        "file": {
                            "status": "Available",
                            "id": "99305805-3844-41b5-af56-ee693ab80527",
                            "name": "Netflix-10-K-01262024.pdf",
                            "size": 1073470,
                            "metadata": null,
                            "updated_on": "2025-07-29T20:07:53.171752661Z",
                            "created_on": "2025-07-29T20:07:36.361322699Z",
                            "signed_url": "https://storage.googleapis.com/..."
                        },
                        "pages": [
                            78,
                            79,
                            80
                        ],
                        "highlight": null
                    },
                    {
                        "file": {
                            "status": "Available",
                            "id": "99305805-3844-41b5-af56-ee693ab80527",
                            "name": "Netflix-10-K-01262024.pdf",
                            "size": 1073470,
                            "metadata": null,
                            "updated_on": "2025-07-29T20:07:53.171752661Z",
                            "created_on": "2025-07-29T20:07:36.361322699Z",
                            "signed_url": "https://storage.googleapis.com/..."
                        },
                        "pages": [
                            77,
                            78
                        ],
                        "highlight": null
                    }
                ]
            }
        ]
    }
    ```
  </Tab>

  <Tab title="Context retrieval">
    For [context retrieval](/guides/assistant/context-snippets-overview), tokens are defined as follows:

    * `prompt_tokens` are based on the messages sent to the assistant and the context snippets retrieved from the assistant. Messages sent to the assistant can include messages from the chat history in addition to the newest message.

      `prompt_tokens` appear as **Assistants Context Tokens Processed** on invoices.

    * `completion_tokens` do not apply for context retrieval because, unlike for chat, there is no answer from a model. `completion_tokens` will always be 0.

    * `total_tokens` is the sum of `prompt_tokens` and `completion_tokens`.

    ```json Example context response {30-34} theme={null}
    {
        "snippets": [
            {
                "type": "text",
                "content": "edures, or caused such disclosure controls and procedures to be designed under our supervision, to\r\nensure that material information relating to the registrant, including its consolidated subsidiaries, ...",
                "score": 0.86632514,
                "reference": {
                    "type": "pdf",
                    "file": {
                        "status": "Available",
                        "id": "99305805-3844-41b5-af56-ee693ab80527",
                        "name": "Netflix-10-K-01262024.pdf",
                        "size": 1073470,
                        "metadata": null,
                        "updated_on": "2025-07-29T20:07:53.171752661Z",
                        "created_on": "2025-07-29T20:07:36.361322699Z",
                        "signed_url": "https://storage.googleapis.com/..."
                    },
                    "pages": [
                        78,
                        79,
                        80
                    ]
                }
            },
            ...
        ],
        "usage": {
            "prompt_tokens": 22914,
            "completion_tokens": 0,
            "total_tokens": 22914
        },
        "id": "00000000000000007b6ad859184a31b3"
    }
    ```
  </Tab>

  <Tab title="Response evaluation">
    For [response evaluation](/guides/assistant/evaluation-overview), tokens are defined as follows:

    * `prompt_tokens` are based on two requests to a model: The first request contains a question, answer, and ground truth answer, and the second request contains the same details plus generated facts returned by the model for the first request.

      `prompt_tokens` appear as **Assistants Evaluation Tokens Processed** on invoices.
    * `completion_tokens` are based on two responses from a model: The first response contains generated facts, and the second response contains evaluation metrics.

      `completion_tokens` appear as **Assistants Evaluation Tokens Out** on invoices.
    * `total_tokens` is the sum of `prompt_tokens` and `completion_tokens`.

    ```json Response evaluation response {17-21} theme={null}
    {
      "metrics": {
        "correctness": 123,
        "completeness": 123,
        "alignment": 123
      },
      "reasoning": {
        "evaluated_facts": [
          {
            "fact": {
              "content": "<string>"
            },
            "entailment": "entailed"
          }
        ]
      },
      "usage": {
        "prompt_tokens": 123,
        "completion_tokens": 123,
        "total_tokens": 123
      }
    }
    ```
  </Tab>
</Tabs>


# Projects overview
Source: https://docs.pinecone.io/guides/assistant/admin/projects-overview

Understand how Pinecone projects contain assistants, indexes, and users, and review project owner and project user roles and their permissions.

A Pinecone project belongs to an [organization](/guides/assistant/admin/organizations-overview) and contains a number of [assistants](/guides/assistant/overview) and users. Only a user who belongs to the project can access the assistants in that project. Each project also has at least one project owner.

## Project roles

If you are an [organization owner](/guides/assistant/admin/organizations-overview#organization-roles) or project owner, you can manage who has access to a project. You grant a principal—a user, [service account](/guides/assistant/admin/manage-project-service-accounts), or [API key](/guides/assistant/admin/manage-api-keys)—access by assigning it one or more roles scoped to the project. A principal can hold more than one role, and its effective permissions are the union of all the roles it holds.

The roles you assign depend on the principal type:

* **Users and service accounts** are typically assigned a membership role—`ProjectOwner`, `ProjectManager`, or `ProjectMember`—optionally combined with one or more access roles.
* **API keys** are typically assigned `ProjectEditor` or `ProjectViewer`, or one or more access roles. API keys cannot be assigned `ProjectOwner`, `ProjectManager`, or `ProjectMember`, which include access to project settings, members, and API keys. To access these items programmatically, use a [service account](/guides/assistant/admin/manage-project-service-accounts).

The following project roles are available:

| Role                                        | Permissions                                                                                                                     |
| :------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------ |
| Project owner (`ProjectOwner`)              | Full access to the project, including members, API keys, and all resources and data.                                            |
| Project manager (`ProjectManager`)          | Read and write access to all resources and data. Read-only access to project settings, members, and API keys.                   |
| Project member (`ProjectMember`)            | Read-only access to project settings, members, and API keys. No resource or data access unless granted additional access roles. |
| Project editor (`ProjectEditor`)            | Read and write access to all resources and data. No access to project settings, members, or API keys.                           |
| Project viewer (`ProjectViewer`)            | Read-only access to all resources and data. No access to project settings, members, or API keys.                                |
| Control plane editor (`ControlPlaneEditor`) | Read and write access to control plane resources, such as indexes, assistants, backups, and collections.                        |
| Control plane viewer (`ControlPlaneViewer`) | Read-only access to control plane resources.                                                                                    |
| Data plane editor (`DataPlaneEditor`)       | Read and write access to data plane data, such as records, namespaces, and assistant files.                                     |
| Data plane viewer (`DataPlaneViewer`)       | Read-only access to data plane data.                                                                                            |

The following table details the project settings, resource, and data permissions for the owner, manager, and member roles:

| Permission                                                                  | Owner | Manager | Member |
| :-------------------------------------------------------------------------- | :---: | :-----: | :----: |
| View project settings, members, and API keys                                |   ✓   |    ✓    |    ✓   |
| Update project settings and configuration                                   |   ✓   |         |        |
| Delete the project                                                          |   ✓   |         |        |
| Manage project members and their roles                                      |   ✓   |         |        |
| Create and delete API keys                                                  |   ✓   |         |        |
| View indexes, assistants, backups, and collections                          |   ✓   |    ✓    |        |
| Create, configure, and delete indexes, assistants, backups, and collections |   ✓   |    ✓    |        |
| Read index data (query, fetch, list, and view stats)                        |   ✓   |    ✓    |        |
| Write index data (upsert, update, delete, and import)                       |   ✓   |    ✓    |        |

Specific to pod-based indexes:

<Warning>
  Customers who sign up for a Standard or Enterprise plan on or after August 18, 2025 cannot create pod-based indexes. Instead, create [serverless indexes](/guides/index-data/create-an-index), and consider using [dedicated read nodes](/guides/index-data/dedicated-read-nodes) for large workloads (millions of records or more, and moderate or high query rates).
</Warning>

| Permission                | Owner | Manager | Member |
| :------------------------ | :---: | :-----: | :----: |
| View project pod limits   |   ✓   |    ✓    |    ✓   |
| Update project pod limits |   ✓   |         |        |
| Update index size         |   ✓   |    ✓    |        |

<Note>
  Pod-based indexes do not support role-based access control and will always grant data plane read and write access to project members.
</Note>

### Role permissions

The following tables detail the operations covered by the general, control plane, and data plane roles:

#### General permissions

| Role            | Permissions                                     |
| :-------------- | :---------------------------------------------- |
| `ProjectEditor` | Permissions to read and write all project data. |
| `ProjectViewer` | Permissions to read all project data.           |

#### Control plane permissions

| Role                 | Permissions                                                                                                 |
| :------------------- | :---------------------------------------------------------------------------------------------------------- |
| `ControlPlaneEditor` | Permissions to list, describe, create, delete, and configure indexes, backups, collections, and assistants. |
| `ControlPlaneViewer` | Permissions to list and describe indexes, backups, collections, and assistants.                             |
| None                 | No control plane permissions.                                                                               |

#### Data plane permissions

| Role              | Permissions                                                                                                                                                                                                                                                                                                            |
| :---------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DataPlaneEditor` | <ul><li>Indexes: Permissions to query, import, fetch, add, update, and delete index data.</li><li>Pinecone Assistant: Permissions to add, list, view, and delete files; chat with an assistant, and evaluate responses.</li><li>Pinecone Inference: Permissions to generate embeddings and rerank documents.</li></ul> |
| `DataPlaneViewer` | <ul><li>Indexes: Permissions to query, fetch, list ID, and view stats.</li><li>Pinecone Assistant: Permissions to list and view files, chat with an assistant, and evaluate responses.</li><li>Pinecone Inference: Permissions to generate embeddings and rerank documents.</li></ul>                                  |
| None              | No data plane permissions.                                                                                                                                                                                                                                                                                             |

## API keys

Each Pinecone [project](/guides/assistant/admin/projects-overview) has one or more API keys. In order to [make calls to the Pinecone API](/guides/assistant/quickstart/sdk-quickstart), you must provide a valid API key for the relevant Pinecone project.

For more information, see [Manage API keys](/guides/assistant/admin/manage-api-keys).

## Service accounts

<Note>
  This feature is in [public preview](/release-notes/feature-availability) and available only on [Enterprise plans](https://www.pinecone.io/pricing/).
</Note>

[Service accounts](/guides/assistant/admin/manage-organization-service-accounts) enable programmatic access to Pinecone's Admin API, which can be used to create and manage projects and API keys.

Use service accounts to automate infrastructure management and integrate Pinecone into your deployment workflows, rather than through manual actions in the Pinecone console. Service accounts use the [organization roles](/guides/assistant/admin/organizations-overview#organization-roles) and [project role](/guides/assistant/admin/projects-overview#project-roles) for permissioning, and provide a secure and auditable way to handle programmatic access.

To use service accounts, [add the account to your organization](/guides/assistant/admin/manage-organization-service-accounts) before [connecting it to a project](/guides/assistant/admin/manage-project-service-accounts).

## Project IDs

Each Pinecone project has a unique project ID.

To find the ID of a project, go to the project list in the [Pinecone console](https://app.pinecone.io/organizations/-/projects).

## See also

* [Create a project](/guides/assistant/admin/create-a-project)
* [Manage project members](/guides/assistant/admin/manage-project-members)
* [Organizations overview](/guides/assistant/admin/organizations-overview)


# Create an API key
Source: https://docs.pinecone.io/reference/api/2026-04/admin-assistant/create_api_key

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml post /admin/projects/{project_id}/api-keys
Create an API key for a project to authenticate Data Plane and Control Plane requests.


<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  // `value` is returned only at creation time and cannot be retrieved later
  const apiKey = await admin.apiKeys.create('YOUR_PROJECT_ID', {
    name: 'Example API Key',
    roles: ['ProjectEditor'],
  });
  console.log(apiKey);
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "fmt"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{})
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      roles := []string{"ProjectEditor"}
      apiKey, err := adminClient.APIKey.Create(ctx, "YOUR_PROJECT_ID", &pinecone.CreateAPIKeyParams{
          Name:  "Example API Key",
          Roles: &roles,
      })
      if err != nil {
          log.Fatalf("Failed to create API key: %v", err)
      }
      // Value is returned only at creation time and cannot be retrieved later
      fmt.Printf("Successfully created API key: %v\n", apiKey.Key.Id)
  }
  ```

  ```hcl Terraform theme={null}
  # Requires Terraform provider v4.0.0 or later
  resource "pinecone_api_key" "example" {
    name       = "Example API Key"
    project_id = "YOUR_PROJECT_ID"
    roles      = ["ProjectEditor"]
  }
  ```

  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
  PINECONE_PROJECT_ID="YOUR_PROJECT_ID"

  curl "https://api.pinecone.io/admin/projects/$PINECONE_PROJECT_ID/api-keys" \
  	-H "X-Pinecone-Api-Version: 2026-04" \
  	-H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
  	-d '{
  		"name": "Example API Key",
  		"roles": ["ProjectEditor"]
  	}'
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "key": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Example API key",
      "project_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "roles": [
        "ProjectEditor"
      ]
    },
    "value": "string"
  }
  ```
</ResponseExample>


# Create a new project
Source: https://docs.pinecone.io/reference/api/2026-04/admin-assistant/create_project

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml post /admin/projects
Create a new project.

<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  const project = await admin.projects.create({ name: 'example-project' });
  console.log(project);
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "fmt"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      project, err := adminClient.Project.Create(ctx, &pinecone.CreateProjectParams{
          Name: "example-project",
      })
      if err != nil {
          log.Fatalf("Failed to create project: %v", err)
      }
      fmt.Printf("Successfully created project: %v\n", project.Id)
  }
  ```

  ```hcl Terraform theme={null}
  # Requires Terraform provider v4.0.0 or later
  resource "pinecone_project" "example" {
    name = "example-project"
  }
  ```

  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

  curl "https://api.pinecone.io/admin/projects" \
      -H "X-Pinecone-Api-Version: 2026-04" \
  	-H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
  	-d '{
          "name":"example-project"
          }'
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "example-project",
    "max_pods": 0,
    "force_encryption_with_cmek": false,
    "organization_id": "string",
    "created_at": "2025-03-16T22:46:45.030Z"
  }
  ```
</ResponseExample>


# Delete an API key
Source: https://docs.pinecone.io/reference/api/2026-04/admin-assistant/delete_api_key

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml delete /admin/api-keys/{api_key_id}
Delete an API key from a project.

<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  await admin.apiKeys.delete('YOUR_API_KEY_ID');
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      if err := adminClient.APIKey.Delete(ctx, "YOUR_API_KEY_ID"); err != nil {
          log.Fatalf("Failed to delete API key: %v", err)
      }
  }
  ```

  ```hcl Terraform theme={null}
  # Requires Terraform provider v4.0.0 or later
  # This block defines the API key. To delete it, either remove the block and run
  # `terraform apply`, or run:
  #   terraform destroy -target=pinecone_api_key.example
  resource "pinecone_api_key" "example" {
    name       = "Example API Key"
    project_id = "YOUR_PROJECT_ID"
  }
  ```

  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
  PINECONE_API_KEY_ID="YOUR_KEY_ID"

  curl -X DELETE "https://api.pinecone.io/admin/api-keys/$PINECONE_API_KEY_ID" \
  	-H "X-Pinecone-Api-Version: 2026-04" \
  	-H "Authorization: Bearer $PINECONE_ACCESS_TOKEN"
  ```
</RequestExample>


# Delete a project
Source: https://docs.pinecone.io/reference/api/2026-04/admin-assistant/delete_project

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml delete /admin/projects/{project_id}
Delete a project and all its configuration; delete its indexes, assistants, backups, and collections first.


<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  await admin.projects.delete('YOUR_PROJECT_ID');
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      if err := adminClient.Project.Delete(ctx, "YOUR_PROJECT_ID"); err != nil {
          log.Fatalf("Failed to delete project: %v", err)
      }
  }
  ```

  ```hcl Terraform theme={null}
  # Requires Terraform provider v4.0.0 or later
  # This block defines the project. To delete it, either remove the block and run
  # `terraform apply`, or run:
  #   terraform destroy -target=pinecone_project.example
  resource "pinecone_project" "example" {
    name = "example-project"
  }
  ```

  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
  PROJECT_ID="YOUR_PROJECT_ID"

  curl -X DELETE "https://api.pinecone.io/admin/projects/$PROJECT_ID" \
  	-H "X-Pinecone-Api-Version: 2026-04" \
  	-H "Authorization: Bearer $PINECONE_ACCESS_TOKEN"
  ```
</RequestExample>


# Get API key details
Source: https://docs.pinecone.io/reference/api/2026-04/admin-assistant/fetch_api_key

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml get /admin/api-keys/{api_key_id}
Get an API key's details, excluding its secret.

<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  const apiKey = await admin.apiKeys.describe('YOUR_API_KEY_ID');
  console.log(apiKey);
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "fmt"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      apiKey, err := adminClient.APIKey.Describe(ctx, "YOUR_API_KEY_ID")
      if err != nil {
          log.Fatalf("Failed to describe API key: %v", err)
      }
      fmt.Printf("API key: %v (%v)\n", apiKey.Name, apiKey.Id)
  }
  ```

  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
  PINECONE_API_KEY_ID="3fa85f64-5717-4562-b3fc-2c963f66afa6"

  curl -X GET "https://api.pinecone.io/admin/api-keys/$PINECONE_API_KEY_ID" \
  	-H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
      -H "accept: application/json" \
      -H "X-Pinecone-Api-Version: 2026-04"
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "string",
    "project_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "roles": [
      "ProjectEditor"
    ]
  }
  ```
</ResponseExample>


# Get project details
Source: https://docs.pinecone.io/reference/api/2026-04/admin-assistant/fetch_project

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml get /admin/projects/{project_id}
Get a project's details.

<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  const project = await admin.projects.describe('YOUR_PROJECT_ID');
  console.log(project);
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "fmt"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      project, err := adminClient.Project.Describe(ctx, "YOUR_PROJECT_ID")
      if err != nil {
          log.Fatalf("Failed to describe project: %v", err)
      }
      fmt.Printf("Project: %v (%v)\n", project.Name, project.Id)
  }
  ```

  ```hcl Terraform theme={null}
  # Requires Terraform provider v4.0.0 or later
  data "pinecone_project" "example" {
    id = "YOUR_PROJECT_ID"
  }

  output "project_name" {
    value = data.pinecone_project.example.name
  }
  ```

  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
  PROJECT_ID="3fa85f64-5717-4562-b3fc-2c963f66afa6"

  curl -X GET "https://api.pinecone.io/admin/projects/$PROJECT_ID" \
      -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
  	-H "X-Pinecone-Api-Version: 2026-04" \
      -H "accept: application/json"
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "example-project",
    "max_pods": 0,
    "force_encryption_with_cmek": false,
    "organization_id": "string",
    "created_at": "2025-03-17T00:30:23.262Z"
  }
  ```
</ResponseExample>


# Create an access token
Source: https://docs.pinecone.io/reference/api/2026-04/admin-assistant/get_token

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/oauth_2026-04.oas.yaml post /oauth/token
Obtain an access token for a service account using the OAuth2 client credentials flow. An access token is needed to authorize requests to the Pinecone Admin API.
The host domain for OAuth endpoints is `login.pinecone.io`.


<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // You don't call this endpoint directly when using the SDK. The AdminClient
  // exchanges your service account credentials for an access token on the first
  // admin request and reuses it for subsequent calls.
  const admin = new AdminClient({
    clientId: 'YOUR_CLIENT_ID',
    clientSecret: 'YOUR_CLIENT_SECRET',
  });

  const { data: projects } = await admin.projects.list();
  console.log(projects);
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "fmt"
      "log"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      // You don't call this endpoint directly when using the SDK. The AdminClient
      // exchanges your service account credentials for an access token.
      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     "YOUR_CLIENT_ID",
          ClientSecret: "YOUR_CLIENT_SECRET",
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      projects, err := adminClient.Project.List(ctx)
      if err != nil {
          log.Fatalf("Failed to list projects: %v", err)
      }
      fmt.Printf("Found %v projects\n", len(projects))
  }
  ```

  ```bash curl theme={null}
  curl "https://login.pinecone.io/oauth/token" \ # Note: Base URL is login.pinecone.io
  	-H "X-Pinecone-Api-Version: 2026-04" \
  	-H "Content-Type: application/json" \
  	-d '{
  		"grant_type": "client_credentials",
  		"client_id": "YOUR_CLIENT_ID",
  		"client_secret": "YOUR_CLIENT_SECRET",
  		"audience": "https://api.pinecone.io/"
  	}'
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
      "access_token":"YOUR_ACCESS_TOKEN",
      "expires_in":86400,
      "token_type":"Bearer"
  }
  ```
</ResponseExample>


# List API keys
Source: https://docs.pinecone.io/reference/api/2026-04/admin-assistant/list_api_keys

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml get /admin/projects/{project_id}/api-keys
List all API keys in a project.

<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  const { data: apiKeys } = await admin.apiKeys.list('YOUR_PROJECT_ID');
  console.log(apiKeys);
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "fmt"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      apiKeys, err := adminClient.APIKey.List(ctx, "YOUR_PROJECT_ID")
      if err != nil {
          log.Fatalf("Failed to list API keys: %v", err)
      }
      for _, apiKey := range apiKeys {
          fmt.Printf("API key: %v (%v)\n", apiKey.Name, apiKey.Id)
      }
  }
  ```

  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
  PINECONE_PROJECT_ID="YOUR_PROJECT_ID"

  curl -X GET "https://api.pinecone.io/admin/projects/$PINECONE_PROJECT_ID/api-keys" \
      -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
      -H "X-Pinecone-Api-Version: 2026-04"
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "data": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "name": "string",
        "project_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "roles": [
          "ProjectEditor"
        ]
      }
    ]
  }
  ```
</ResponseExample>


# List projects
Source: https://docs.pinecone.io/reference/api/2026-04/admin-assistant/list_projects

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml get /admin/projects
List all projects in an organization.

<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  const { data: projects } = await admin.projects.list();
  console.log(projects);
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "fmt"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      projects, err := adminClient.Project.List(ctx)
      if err != nil {
          log.Fatalf("Failed to list projects: %v", err)
      }
      for _, project := range projects {
          fmt.Printf("Project: %v (%v)\n", project.Name, project.Id)
      }
  }
  ```

  ```hcl Terraform theme={null}
  # Requires Terraform provider v4.0.0 or later
  data "pinecone_projects" "all" {}

  output "project_names" {
    value = [for project in data.pinecone_projects.all.projects : project.name]
  }
  ```

  ```bash curl theme={null}
  curl -X GET "https://api.pinecone.io/admin/projects" \
      -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
      -H "X-Pinecone-Api-Version: 2026-04"
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "data": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "name": "example-project",
        "max_pods": 0,
        "force_encryption_with_cmek": true,
        "organization_id": "<string>",
        "created_at": "2023-11-07T05:31:56Z"
      }
    ]
  }
  ```
</ResponseExample>


# Update an API key
Source: https://docs.pinecone.io/reference/api/2026-04/admin-assistant/update_api_key

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml patch /admin/api-keys/{api_key_id}
Update an API key's name and roles.

<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  const apiKey = await admin.apiKeys.update('YOUR_API_KEY_ID', {
    name: 'New API key name',
    roles: ['ProjectEditor'],
  });
  console.log(apiKey);
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "fmt"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      name := "New API key name"
      roles := []string{"ProjectEditor"}
      apiKey, err := adminClient.APIKey.Update(ctx, "YOUR_API_KEY_ID", &pinecone.UpdateAPIKeyParams{
          Name:  &name,
          Roles: &roles,
      })
      if err != nil {
          log.Fatalf("Failed to update API key: %v", err)
      }
      fmt.Printf("Successfully updated API key: %v\n", apiKey.Name)
  }
  ```

  ```hcl Terraform theme={null}
  # Requires Terraform provider v4.0.0 or later
  # Change the name or roles on an existing resource, then run `terraform apply`
  resource "pinecone_api_key" "example" {
    name       = "New API key name"
    project_id = "YOUR_PROJECT_ID"
    roles      = ["ProjectEditor"]
  }
  ```

  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
  PINECONE_API_KEY_ID="YOUR_API_KEY_ID"

  curl -X PATCH "https://api.pinecone.io/admin/api-keys/$PINECONE_API_KEY_ID" \
  	-H "X-Pinecone-Api-Version: 2026-04" \
  	-H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
  	-d '{
  		"name": "New API key name",
  		"roles": ["ProjectEditor"]
  	}'
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "key": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "New API key name",
      "project_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "roles": [
        "ProjectEditor"
      ]
    },
    "value": "string"
  }
  ```
</ResponseExample>


# Update a project
Source: https://docs.pinecone.io/reference/api/2026-04/admin-assistant/update_project

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml patch /admin/projects/{project_id}
Update a project's name, maximum number of Pods, or customer-managed encryption key (CMEK).


<RequestExample>
  ```javascript JavaScript theme={null}
  // Requires Node.js SDK v8.2.0 or later
  import { AdminClient } from '@pinecone-database/pinecone';

  // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment
  const admin = new AdminClient();

  const project = await admin.projects.update('YOUR_PROJECT_ID', {
    name: 'updated-example-project',
  });
  console.log(project);
  ```

  ```go Go theme={null}
  // Requires Go SDK v6.0.0 or later
  package main

  import (
      "context"
      "fmt"
      "log"
      "os"

      "github.com/pinecone-io/go-pinecone/v6/pinecone"
  )

  func main() {
      ctx := context.Background()

      adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{
          ClientId:     os.Getenv("PINECONE_CLIENT_ID"),
          ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"),
      })
      if err != nil {
          log.Fatalf("Failed to create AdminClient: %v", err)
      }

      name := "updated-example-project"
      project, err := adminClient.Project.Update(ctx, "YOUR_PROJECT_ID", &pinecone.UpdateProjectParams{
          Name: &name,
      })
      if err != nil {
          log.Fatalf("Failed to update project: %v", err)
      }
      fmt.Printf("Successfully updated project: %v\n", project.Name)
  }
  ```

  ```hcl Terraform theme={null}
  # Requires Terraform provider v4.0.0 or later
  # Change the name on an existing resource, then run `terraform apply`
  resource "pinecone_project" "example" {
    name = "updated-example-project"
  }
  ```

  ```bash curl theme={null}
  PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
  PROJECT_ID="YOUR_PROJECT_ID"

  curl -X PATCH "https://api.pinecone.io/admin/projects/$PROJECT_ID" \
    -H "accept: application/json" \
    -H "Content-Type: application/json" \
    -H "X-Pinecone-Api-Version: 2026-04" \
    -d '{
      "name": "updated-example-project"
      }'
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "updated-example-project",
    "max_pods": 0,
    "force_encryption_with_cmek": false,
    "organization_id": "string",
    "created_at": "2025-03-17T00:42:31.912Z"
  }
  ```
</ResponseExample>


# Chat with an assistant
Source: https://docs.pinecone.io/reference/api/2026-04/assistant/chat_assistant

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/assistant_data_2026-04.oas.yaml POST /chat/{assistant_name}
Chat with an assistant and get back citations in structured form. 

This is the recommended way to chat with an assistant, as it offers more functionality and control over the assistant's responses and references than the OpenAI-compatible chat interface.

For guidance and examples, see [Chat with an assistant](https://docs.pinecone.io/guides/assistant/chat-with-assistant).

<RequestExample>
  ```bash curl | Default theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  ASSISTANT_NAME="example-assistant"

  curl "https://prod-1-data.ke.pinecone.io/assistant/chat/$ASSISTANT_NAME" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "messages": [
      {
        "role": "user",
        "content": "What is the inciting incident of Pride and Prejudice?"
      }
    ],
    "stream": false,
    "model": "gpt-4o"
  }'
  ```

  ```bash curl | Streaming theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  ASSISTANT_NAME="example-assistant"

  curl "https://prod-1-data.ke.pinecone.io/assistant/chat/$ASSISTANT_NAME" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "Content-Type: application/json" \
    -H "X-Pinecone-Api-Version: 2026-04" \
    -d '{
    "messages": [
      {
        "role": "user",
        "content": "What is the inciting incident of Pride and Prejudice?"
      }
    ],
    "stream": true,
    "model": "gpt-4o"
  }'
  ```
</RequestExample>

<ResponseExample>
  ```json Default response theme={null}
  {
    "finish_reason": "stop",
    "message": {
      "role": "assistant",
      "content": "The inciting incident of \"Pride and Prejudice\" occurs when Mrs. Bennet informs Mr. Bennet that Netherfield Park has been let at last, and she is eager to share the news about the new tenant, Mr. Bingley, who is wealthy and single. This sets the stage for the subsequent events of the story, including the introduction of Mr. Bingley and Mr. Darcy to the Bennet family and the ensuing romantic entanglements."
    },
    "id": "00000000000000004ac3add5961aa757",
    "model": "gpt-4o-2024-05-13",
    "usage": {
      "prompt_tokens": 9736,
      "completion_tokens": 105,
      "total_tokens": 9841
    },
    "citations": [
      {
        "position": 406,
        "references": [
          {
            "file": {
              "status": "Available",
              "id": "ae79e447-b89e-4994-994b-3232ca52a654",
              "name": "Pride-and-Prejudice.pdf",
              "size": 2973077,
              "metadata": null,
              "updated_on": "2024-06-14T15:01:57.385425746Z",
              "created_on": "2024-06-14T15:01:02.910452398Z",
              "signed_url": "https://storage.googleapis.com/..."
            },
            "pages": [
              1
            ]
          }
        ]
      }
    ]
  }

  ```

  ```text Streaming response theme={null}
  data:{
    "type":"message_start",
    "id":"0000000000000000111b35de85e8a8f9",
    "model":"gpt-4o-2024-05-13",
    "role":"assistant"
  }

  data:
  {
    "type":"content_chunk",
    "id":"0000000000000000111b35de85e8a8f9",
    "model":"gpt-4o-2024-05-13",
    "delta":
    {
      "content":"The"
      }
  }

  ...

  data:
  {
    "type":"citation",
    "id":"0000000000000000111b35de85e8a8f9",
    "model":"gpt-4o-2024-05-13",
    "citation":
    {
      "position":406,
      "references":
      [
        {
          "file":{
            "status":"Available",
            "id":"ae79e447-b89e-4994-994b-3232ca52a654",
            "name":"Pride-and-Prejudice.pdf",
            "size":2973077,
            "metadata":null,
            "updated_on":"2024-06-14T15:01:57.385425746Z",
            "created_on":"2024-06-14T15:01:02.910452398Z",
            "signed_url":"https://storage.googleapis.com/..."
            },
        "pages":[1]
        }
      ]
    }
  }

  data:
  {
    "type":"message_end",
    "id":"0000000000000000111b35de85e8a8f9",
    "model":"gpt-4o-2024-05-13",
    "finish_reason":"stop",
    "usage":
    {
      "prompt_tokens":9736,
      "completion_tokens":102,
      "total_tokens":9838
      }
  }
  ```
</ResponseExample>


# Chat through an OpenAI-compatible interface
Source: https://docs.pinecone.io/reference/api/2026-04/assistant/chat_completion_assistant

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/assistant_data_2026-04.oas.yaml POST /chat/{assistant_name}/chat/completions
Chat with an assistant. This endpoint is based on the OpenAI Chat Completion API, a commonly used and adopted API. 

It is useful if you need inline citations or OpenAI-compatible responses, but has limited functionality compared to the standard chat interface.

For guidance and examples, see [Chat with an assistant](https://docs.pinecone.io/guides/assistant/chat-with-assistant).

<RequestExample>
  ```bash curl | Default theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  ASSISTANT_NAME="example-assistant"

  curl "https://prod-1-data.ke.pinecone.io/assistant/chat/$ASSISTANT_NAME/chat/completions" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "messages": [
      {
        "role": "user",
        "content": "What is the maximum height of a red pine?"
      }
    ]
  }'
  ```

  ```bash curl | Streaming theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  ASSISTANT_NAME="example-assistant"

  curl "https://prod-1-data.ke.pinecone.io/assistant/chat/$ASSISTANT_NAME/chat/completions" \
    -H "Api-Key: $PINECONE_API_KEY "\
    -H "Content-Type: application/json" \
    -H "X-Pinecone-Api-Version: 2026-04" \
    -d '{
    "messages": [
      {
        "role": "user",
        "content": "What is the maximum height of a red pine?"
      }
    ],
    "stream": true
  }'
  ```
</RequestExample>

<ResponseExample>
  ```JSON Default response theme={null}
  {"chat_completion":
    {
      "id":"chatcmpl-9OtJCcR0SJQdgbCDc9JfRZy8g7VJR",
      "choices":[
        {
          "finish_reason":"stop",
          "index":0,
          "message":{
            "role":"assistant",
            "content":"The maximum height of a red pine (Pinus resinosa) is up to 25 meters."
          }
        }
      ],
      "model":"my_assistant"
    }
  }
  ```

  ```text Streaming response theme={null}
  {
    'id': '000000000000000009de65aa87adbcf0',
    'choices': [
        {
        'index': 0,
        'delta':
          {
          'role': 'assistant',
          'content': 'The'
          },
        'finish_reason': None
        }
      ],
    'model': 'gpt-4o-2024-05-13'
  }

  ...

  {
    'id': '00000000000000007a927260910f5839',
    'choices': [
        {
        'index': 0,
        'delta':
          {
            'role': '',
            'content': 'The'
          },
        'finish_reason': None
        }
      ],
    'model': 'gpt-4o-2024-05-13'
  }

  ...

  {
    'id': '00000000000000007a927260910f5839',
    'choices': [
      {
        'index': 0,
        'delta':
          {
          'role': None,
          'content': None
          },
        'finish_reason': 'stop'
        }
      ],
    'model': 'gpt-4o-2024-05-13'
  }
  ```
</ResponseExample>


# Retrieve context from an assistant
Source: https://docs.pinecone.io/reference/api/2026-04/assistant/context_assistant

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/assistant_data_2026-04.oas.yaml POST /chat/{assistant_name}/context
Retrieve context snippets from an assistant to use as part of RAG or any agentic flow.

For guidance and examples, see [Retrieve context snippets](https://docs.pinecone.io/guides/assistant/retrieve-context-snippets).

<RequestExample>
  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  ASSISTANT_NAME="example-assistant"

  curl "https://prod-1-data.ke.pinecone.io/assistant/chat/$ASSISTANT_NAME/context" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "accept: application/json" \
    -H "Content-Type: application/json" \
    -H "X-Pinecone-Api-Version: 2026-04" \
    -d '{
      "query": "Who is the CFO of Netflix?"
  }'
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
      "snippets":
      [
          {
              "type":"text",
              "content":"EXHIBIT 31.3\nCERTIFICATION OF CHIEF FINANCIAL OFFICER\nPURSUANT TO SECTION 302 OF THE SARBANES-OXLEY ACT OF 2002\nI, Spencer Neumann, certify that: ...",
              "score":0.9960699,
              "reference":
              {
                  "type":"pdf",
                  "file":
                  {
                      "status":"Available","id":"e6034e51-0bb9-4926-84c6-70597dbd07a7",
                      "name":"Netflix-10-K-01262024.pdf",
                      "size":1073470,
                      "metadata":null,
                      "updated_on":"2024-11-21T22:59:10.426001030Z",
                      "created_on":"2024-11-21T22:58:35.879120257Z",
                      "signed_url":"https://storage.googleapis.com..."
                      },
                  "pages":[78]
              }
          },
  {
      "type":"text",
      "content":"EXHIBIT 32.1\n..."
  ...
  ```
</ResponseExample>


# Create an assistant
Source: https://docs.pinecone.io/reference/api/2026-04/assistant/create_assistant

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/assistant_control_2026-04.oas.yaml POST /assistants
Create an assistant. This is where you specify the underlying training model, which cloud provider you would like to deploy with, and more.

For guidance and examples, see [Create an assistant](https://docs.pinecone.io/guides/assistant/create-assistant)

<RequestExample>
  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"

  curl "https://api.pinecone.io/assistant/assistants" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "Content-Type: application/json" \
    -H "X-Pinecone-Api-Version: 2026-04" \
    -d '{
    "name": "example-assistant",
    "instructions": "Use American English for spelling and grammar.",
    "metadata": {"team": "customer-support", "version": "1.0"},
    "region":"us"
  }'
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "name": "example-assistant",
    "instructions": "Use American English for spelling and grammar.",
    "metadata": {"team": "customer-support", "version": "1.0"},
    "status": "Initializing",
    "host": "https://prod-1-data.ke.pinecone.io",
    "created_at": "2025-10-01T12:30:00Z",
    "updated_at": "2025-10-01T12:30:00Z"
  }
  ```
</ResponseExample>


# Delete an assistant
Source: https://docs.pinecone.io/reference/api/2026-04/assistant/delete_assistant

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/assistant_control_2026-04.oas.yaml DELETE /assistants/{assistant_name}
Delete an existing assistant.

For guidance and examples, see [Manage assistants](https://docs.pinecone.io/guides/assistant/manage-assistants#delete-an-assistant)

<RequestExample>
  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  ASSISTANT_NAME="example-assistant"

  curl -X DELETE "https://api.pinecone.io/assistant/assistants/$ASSISTANT_NAME" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2026-04"
  ```
</RequestExample>


# Delete a file
Source: https://docs.pinecone.io/reference/api/2026-04/assistant/delete_file

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/assistant_data_2026-04.oas.yaml DELETE /files/{assistant_name}/{assistant_file_id}
[Delete an uploaded file](https://docs.pinecone.io/guides/assistant/manage-files#delete-a-file) from an assistant.

This operation is asynchronous. The response includes an operation ID that can be used to poll for completion via the describe operation endpoint.

<RequestExample>
  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  ASSISTANT_NAME="example-assistant"
  FILE_ID="070513b3-022f-4966-b583-a9b12e0290ff"

  curl -X DELETE "https://prod-1-data.ke.pinecone.io/assistant/files/$ASSISTANT_NAME/$FILE_ID" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2026-04"
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "id": "op-7777-ffff-0000",
    "operation_type": "delete_file",
    "file_id": "my-file-id-123",
    "status": "Processing",
    "created_on": "2025-10-01T12:30:00Z",
    "percent_complete": 0
  }
  ```
</ResponseExample>

<Note>
  This example shows a `Processing` operation. The `error_message` field is present only when the operation status is `Failed`.
</Note>


# Check assistant status
Source: https://docs.pinecone.io/reference/api/2026-04/assistant/describe_assistant

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/assistant_control_2026-04.oas.yaml GET /assistants/{assistant_name}
Get the status of an assistant.

For guidance and examples, see [Manage assistants](https://docs.pinecone.io/guides/assistant/manage-assistants#get-the-status-of-an-assistant)

<RequestExample>
  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  ASSISTANT_NAME="example-assistant"

  curl -X GET "https://api.pinecone.io/assistant/assistants/$ASSISTANT_NAME" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2026-04"
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "name": "example-assistant",
    "instructions": "Use American English for spelling and grammar.",
    "metadata": {"team": "customer-support", "version": "1.0"},
    "status": "Ready",
    "host": "https://prod-1-data.ke.pinecone.io",
    "created_at": "2025-10-01T12:30:00Z",
    "updated_at": "2025-10-01T12:45:00Z"
  }
  ```
</ResponseExample>


# Describe a file
Source: https://docs.pinecone.io/reference/api/2026-04/assistant/describe_file

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/assistant_data_2026-04.oas.yaml GET /files/{assistant_name}/{assistant_file_id}
[Get the current status and metadata of a file](https://docs.pinecone.io/guides/assistant/manage-files#get-the-status-of-a-file) uploaded to an assistant.

<RequestExample>
  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  ASSISTANT_NAME="example-assistant"
  FILE_ID="3c90c3cc-0d44-4b50-8888-8dd25736052a"

  # Describe a file.
  # To get a signed URL in the response, set `include_url` to `true`.
  curl -X GET "https://prod-1-data.ke.pinecone.io/assistant/files/$ASSISTANT_NAME/$FILE_ID?include_url=true" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2026-04"
  ```
</RequestExample>


# Describe an operation
Source: https://docs.pinecone.io/reference/api/2026-04/assistant/describe_operation

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/assistant_data_2026-04.oas.yaml GET /operations/{assistant_name}/{operation_id}
Get the status of an operation.


<RequestExample>
  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  ASSISTANT_NAME="example-assistant"
  OPERATION_ID="op-1234-abcd-5678"

  curl -X GET "https://prod-1-data.ke.pinecone.io/assistant/operations/$ASSISTANT_NAME/$OPERATION_ID" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2026-04"
  ```
</RequestExample>

<Note>
  Operation responses may include `error_message`, but only when the operation status is `Failed`.
</Note>


# List assistants
Source: https://docs.pinecone.io/reference/api/2026-04/assistant/list_assistants

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/assistant_control_2026-04.oas.yaml GET /assistants
List of all assistants in a project.

For guidance and examples, see [Manage assistants](https://docs.pinecone.io/guides/assistant/manage-assistants#list-assistants-for-a-project).

<RequestExample>
  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"

  curl -X GET "https://api.pinecone.io/assistant/assistants" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2026-04"
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "assistants": [
      {
        "name": "example-assistant",
        "instructions": "Use American English for spelling and grammar.",
        "metadata": {"team": "customer-support", "version": "1.0"},
        "status": "Ready",
        "host": "https://prod-1-data.ke.pinecone.io",
        "created_at": "2025-10-01T12:30:00Z",
        "updated_at": "2025-10-01T12:45:00Z"
      }
    ]
  }
  ```
</ResponseExample>


# List Files
Source: https://docs.pinecone.io/reference/api/2026-04/assistant/list_files

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/assistant_data_2026-04.oas.yaml GET /files/{assistant_name}
List all files in an assistant, with an option to filter files with metadata.

For guidance and examples, see [Manage files](https://docs.pinecone.io/guides/assistant/manage-files#list-files-in-an-assistant).

<RequestExample>
  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  ASSISTANT_NAME="example-assistant"

  curl -X GET "https://prod-1-data.ke.pinecone.io/assistant/files/$ASSISTANT_NAME" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2026-04"
  ```
</RequestExample>


# List operations
Source: https://docs.pinecone.io/reference/api/2026-04/assistant/list_operations

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/assistant_data_2026-04.oas.yaml GET /operations/{assistant_name}
List all operations for an assistant. Returns operations that are in progress, as well as recently completed or failed operations.
Both successful and failed operations are retained for 30 days after completion.
Use the `operation_type` and `status` query parameters to filter results.


<RequestExample>
  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  ASSISTANT_NAME="example-assistant"

  # List all operations
  curl -X GET "https://prod-1-data.ke.pinecone.io/assistant/operations/$ASSISTANT_NAME" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2026-04"

  # Filter by status
  # curl -X GET "https://prod-1-data.ke.pinecone.io/assistant/operations/$ASSISTANT_NAME?status=Processing" \
  #   -H "Api-Key: $PINECONE_API_KEY" \
  #   -H "X-Pinecone-Api-Version: 2026-04"
  ```
</RequestExample>


# Evaluate an answer
Source: https://docs.pinecone.io/reference/api/2026-04/assistant/metrics_alignment

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/assistant_evaluation_2026-04.oas.yaml POST /evaluation/metrics/alignment
Evaluate the correctness and completeness of a response from an assistant or a RAG system. The correctness and completeness are evaluated based on the precision and recall of the generated answer with respect to the ground truth answer facts. Alignment is the harmonic mean of correctness and completeness.

For guidance and examples, see [Evaluate answers](https://docs.pinecone.io/guides/assistant/evaluate-answers).

<RequestExample>
  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"

  curl https://prod-1-data.ke.pinecone.io/assistant/evaluation/metrics/alignment \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "Content-Type: application/json" \
    -H "X-Pinecone-Api-Version: 2026-04" \
    -d '{
      "question": "What are the capital cities of France, England and Spain?",
      "answer": "Paris is the capital city of France and Barcelona of Spain",
      "ground_truth_answer": "Paris is the capital city of France, London of England and Madrid of Spain"
  }'
  ```
</RequestExample>


# Update an assistant
Source: https://docs.pinecone.io/reference/api/2026-04/assistant/update_assistant

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/assistant_control_2026-04.oas.yaml PATCH /assistants/{assistant_name}
Update an existing assistant. You can modify the assistant's instructions.

For guidance and examples, see [Manage assistants](https://docs.pinecone.io/guides/assistant/manage-assistants#add-instructions-to-an-assistant).

<RequestExample>
  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  ASSISTANT_NAME="example-assistant"

  curl -X PATCH "https://api.pinecone.io/assistant/assistants/$ASSISTANT_NAME" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "Content-Type: application/json" \
    -H "X-Pinecone-Api-Version: 2026-04" \
    -d '{
    "instructions": "Use American English for spelling and grammar.",
    "metadata": {"team": "customer-support", "version": "1.1"}
  }'
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "name": "example-assistant",
    "instructions": "Use American English for spelling and grammar.",
    "metadata": {"team": "customer-support", "version": "1.1"},
    "status": "Ready",
    "host": "https://prod-1-data.ke.pinecone.io",
    "created_at": "2025-10-01T12:30:00Z",
    "updated_at": "2025-10-01T12:45:00Z"
  }
  ```
</ResponseExample>


# Upload a file
Source: https://docs.pinecone.io/reference/api/2026-04/assistant/upload_file

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/assistant_data_2026-04.oas.yaml POST /files/{assistant_name}
Upload a file to the specified assistant.

An identifier will be generated. To specify a file identifier or to replace file content, use the upsert endpoint (`PUT /files/{assistant_name}/{assistant_file_id}`).

This operation is asynchronous. The response includes an operation ID that can be used to poll for completion via the describe operation endpoint.

For guidance and examples, see [Manage files](https://docs.pinecone.io/guides/assistant/manage-files#upload-a-local-file).

<RequestExample>
  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  ASSISTANT_NAME="example-assistant"
  LOCAL_FILE_PATH="/Users/jdoe/Downloads/example_file.txt"

  curl -X POST "https://prod-1-data.ke.pinecone.io/assistant/files/$ASSISTANT_NAME" \
       -H "Api-Key: $PINECONE_API_KEY" \
       -H "X-Pinecone-Api-Version: 2026-04" \
       -F "file=@$LOCAL_FILE_PATH" \
       -F 'metadata={"published": "2024-01-01", "document_type": "manuscript"}'
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "id": "op-1234-abcd-5678",
    "operation_type": "upload_file",
    "file_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "status": "Processing",
    "created_on": "2025-10-01T12:30:00Z",
    "percent_complete": 0
  }
  ```
</ResponseExample>

<Note>
  This example shows a `Processing` operation. The `error_message` field is present only when the operation status is `Failed`.
</Note>


# Upsert a file
Source: https://docs.pinecone.io/reference/api/2026-04/assistant/upsert_file

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/assistant_data_2026-04.oas.yaml PUT /files/{assistant_name}/{assistant_file_id}
Create or replace a file in the specified assistant. If a file with the given `assistant_file_id` already exists, it will be replaced with the new file. If it doesn't exist, a new file will be created with that identifier.

This operation is asynchronous. The file processing will occur in the background.

For guidance and examples, see [Manage files](https://docs.pinecone.io/guides/assistant/manage-files#upload-a-local-file).

<RequestExample>
  ```bash curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  ASSISTANT_NAME="example-assistant"
  FILE_ID="my-custom-file-id"
  LOCAL_FILE_PATH="/Users/jdoe/Downloads/example_file.txt"

  curl -X PUT "https://prod-1-data.ke.pinecone.io/assistant/files/$ASSISTANT_NAME/$FILE_ID" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2026-04" \
    -F "file=@$LOCAL_FILE_PATH"
  ```
</RequestExample>

<ResponseExample>
  ```json curl theme={null}
  {
    "id": "op-1234-abcd-5678",
    "operation_type": "upsert_file",
    "file_id": "my-custom-file-id",
    "status": "Processing",
    "created_on": "2025-10-01T12:30:00Z",
    "percent_complete": 0
  }
  ```
</ResponseExample>

<Note>
  This example shows a `Processing` operation. The `error_message` field is present only when the operation status is `Failed`.
</Note>


# Pinecone Assistant limits
Source: https://docs.pinecone.io/reference/api/assistant/assistant-limits

Reference for Pinecone Assistant limits, including file size, storage, chat token, and rate limits across the Starter, Builder, Standard, and Enterprise plans.

Pinecone Assistant limits vary based on [subscription plan](https://www.pinecone.io/pricing/).

### Object limits

Object limits are restrictions on the number or size of assistant-related objects. Limits below are scoped **per organization** except for **Assistants per project**, which is scoped per project.

| Metric                              | Starter plan      | Builder plan      | Standard plan | Enterprise plan |
| :---------------------------------- | :---------------- | :---------------- | :------------ | :-------------- |
| Assistants per project              | 5                 | 200               | Unlimited     | Unlimited       |
| File storage per org                | 1 GB              | 3 GB              | Unlimited     | Unlimited       |
| Chat input tokens per org           | 500,000 / month\* | 2,000,000 / month | Unlimited     | Unlimited       |
| Chat output tokens per org          | 300,000 / month   | 1,000,000 / month | Unlimited     | Unlimited       |
| Context retrieval tokens per org    | 500,000 / month   | 2,000,000 / month | Unlimited     | Unlimited       |
| Ingestion units per org             | 1,000 / month     | 10,000 / month    | Unlimited     | Unlimited       |
| File size (.docx, .json, .md, .txt) | 10 MB             | 10 MB             | 10 MB         | 10 MB           |
| File size (.pdf)                    | 10 MB             | 50 MB             | 100 MB        | 100 MB          |
| Metadata size per file              | 16 KB             | 16 KB             | 16 KB         | 16 KB           |

*\*1,000,000 input tokens/month to explore [Marketplace apps](/guides/marketplace) until June 30, 2026.*

Additionally, the following limits apply to [multimodal PDFs](/guides/assistant/multimodal) (currently in [public preview](/release-notes/feature-availability)):

Multimodal PDF processing uses the same [ingestion unit](/guides/assistant/pricing-and-limits#ingestion) as standard uploads; it is billed at about **twice** the standard per-unit rate (see [Pricing and limits](/guides/assistant/pricing-and-limits)). Object and rate limits for assistants also apply—see [#limits](/guides/assistant/pricing-and-limits#limits) and [#rate-limits](/guides/assistant/pricing-and-limits#rate-limits).

| Metric        | Starter plan | Builder plan | Standard plan | Enterprise plan |
| :------------ | :----------- | :----------- | :------------ | :-------------- |
| Max file size | 10 MB        | 10 MB        | 50 MB         | 50 MB           |
| Page limit    | 100          | 100          | 100           | 100             |

### Rate limits

Rate limits help protect your applications from misuse and maintain the health of our shared infrastructure. These limits are designed to support typical production workloads while ensuring reliable performance for all users.

**Most rate limits can be adjusted upon request.** If you need higher limits to scale your application, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) with details about your use case.

Requests that exceed a rate limit fail and return a `429 - TOO_MANY_REQUESTS` status.

<Tip>To handle rate limits, implement [retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic).</Tip>

| Metric                                      | Starter plan  | Builder plan  | Standard plan | Enterprise plan |
| :------------------------------------------ | :------------ | :------------ | :------------ | :-------------- |
| Assistant list/get requests per minute      | 40            | 50            | 100           | 500             |
| Assistant create/update requests per minute | 20            | 25            | 50            | 100             |
| Assistant delete requests per minute        | 20            | 25            | 50            | 100             |
| File get requests per minute                | 100           | 150           | 300           | 6,000           |
| File list requests per minute               | 50            | 75            | 150           | 3,000           |
| File upload requests per minute             | 5             | 15            | 20            | 300             |
| Multimodal PDF upload requests per minute   | 5             | 10            | 20            | 40              |
| File delete requests per minute             | 5             | 15            | 20            | 300             |
| Chat input tokens per minute                | 100,000       | 200,000       | 300,000       | 1,000,000       |
| Chat history tokens per query               | 64,000        | 64,000        | 64,000        | 64,000          |
| Evaluation input tokens per minute          | Not available | Not available | 150,000       | 500,000         |


# Authentication
Source: https://docs.pinecone.io/reference/api/assistant/authentication

Assistant API authentication with API keys, HTTP headers, and SDK client initialization for Pinecone Assistant requests and RAG apps.

All requests to the [Pinecone Assistant API](/reference/api/assistant/introduction) must contain a valid [API key](/guides/production/security-overview#api-keys) for the target project.

## Get an API key

[Create a new API key](https://app.pinecone.io/organizations/-/projects/-/keys) in the Pinecone console, or use the connect widget below to generate a key.

<div>
  <div>
    <div>
      <div />
    </div>
  </div>
</div>

Copy your generated key:

```
PINECONE_API_KEY="{{YOUR_API_KEY}}"

# This API key has ReadWrite access to all indexes in your project.
```

## Initialize a client

When using a Pinecone SDK, initialize a client object with your API key and then reuse the authenicated client in subsquent function calls. For example:

<CodeGroup>
  ```python Python theme={null}
  # To use the Python SDK, install the plugin:
  # pip install --upgrade pinecone pinecone-plugin-assistant

  from pinecone import Pinecone

  pc = Pinecone(api_key="YOUR_API_KEY")

  # Creates an assistant using the API key stored in the client 'pc'.
  assistant = pc.assistant.create_assistant(
      assistant_name="example-assistant",
      instructions="Use American English for spelling and grammar.",
      region="us" 
  )
  ```

  ```javascript JavaScript theme={null}
  import { Pinecone } from '@pinecone-database/pinecone';

  const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' });

  // Creates an index using the API key stored in the client 'pc'.
  const assistant = await pc.createAssistant({
    name: 'example-assistant',
    instructions: 'Use American English for spelling and grammar.',
    region: 'us'
  });
  ```
</CodeGroup>

## Add headers to an HTTP request

All HTTP requests to the Pinecone Assistant API must contain an `Api-Key` header that specifies a valid [API key](/guides/production/security-overview#api-keys) and must be encoded as JSON with the `Content-Type: application/json` header. For example:

```bash curl theme={null}
PINECONE_API_KEY="YOUR_API_KEY"

curl "https://api.pinecone.io/assistant/assistants" \
  -H "Api-Key: $PINECONE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Pinecone-Api-Version: 2025-01" \
  -d '{
  "name": "example-assistant",
  "instructions": "Use American English for spelling and grammar.",
  "region":"us"
}'
```


# Assistant API reference
Source: https://docs.pinecone.io/reference/api/assistant/introduction

Assistant API reference overview covering document upload, chat, and RAG endpoints supported by the Pinecone Python and Node.js SDKs.

Use the [Assistant API](/guides/assistant/quickstart/sdk-quickstart) to upload documents, ask questions, and receive responses that reference your documents. This is known as [retrieval-augmented generation (RAG)](https://www.pinecone.io/learn/retrieval-augmented-generation/).

## SDK support

The following Pinecone SDKs support the Assistant API:

<CardGroup>
  <Card title="Python SDK" icon="python" href="/reference/sdks/python/overview" />

  <Card title="Node.js SDK" icon="node-js" href="/reference/sdks/node/overview" />
</CardGroup>

## Versioning

The Assistant API is versioned to ensure that your applications continue to work as expected as the platform evolves. For more details, see [API versioning](/reference/api/versioning) in the Pinecone Database documentation.


# Pinecone Assistant architecture
Source: https://docs.pinecone.io/reference/architecture/assistant-architecture

Pinecone Assistant architecture overview covering document ingestion, chunking, vector retrieval, and LLM response generation for RAG.

This page describes the architecture for [Pinecone Assistant](/guides/assistant/overview).

## Overview

[Pinecone Assistant](/guides/assistant/overview) runs as a managed service on the Pinecone platform. It uses a combination of machine learning models and information retrieval techniques to provide responses that are informed by your documents. The assistant is designed to be easy to use, requiring minimal setup and no machine learning expertise.

Pinecone Assistant simplifies complex tasks like data chunking, vector search, embedding, and querying while ensuring privacy and security.

<img />

<img />

## Data ingestion

When a [document is uploaded](/guides/assistant/manage-files), the assistant processes the content by chunking it into smaller parts and generating [vector embeddings](https://www.pinecone.io/learn/vector-embeddings-for-developers/) for each chunk. These embeddings are stored in an [index](/guides/index-data/indexing-overview), making them ready for retrieval.

## Data retrieval

During a [chat](/guides/assistant/chat-with-assistant), the assistant processes the message to formulate relevant search queries, which are used to query the index and identify the most relevant chunks from the uploaded content.

## Response generation

After retrieving these chunks, the assistant performs a ranking step to determine which information is most relevant. This [context](/guides/assistant/context-snippets-overview), along with the chat history and [assistant instructions](/guides/assistant/manage-assistants#add-instructions-to-an-assistant), is then used by a large language model (LLM) to generate responses that are informed by your documents.


# Current identity (whoami)
Source: https://docs.pinecone.io/api-reference/auth/current-identity-whoami

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/nexus_2026-07.oas.yaml get /auth



# Exchange a Pinecone API key for a session token
Source: https://docs.pinecone.io/api-reference/auth/exchange-a-pinecone-api-key-for-a-session-token

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/nexus_2026-07.oas.yaml post /auth/login



# Browse a connector's folders/files
Source: https://docs.pinecone.io/api-reference/connectors/browse-a-connectors-foldersfiles

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/nexus_2026-07.oas.yaml get /connectors/{id}/items



# Enable or disable a connector for a context
Source: https://docs.pinecone.io/api-reference/connectors/enable-or-disable-a-connector-for-a-context

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/nexus_2026-07.oas.yaml put /contexts/{slug}/connectors/{connector_id}



# Get a connector
Source: https://docs.pinecone.io/api-reference/connectors/get-a-connector

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/nexus_2026-07.oas.yaml get /connectors/{id}



# Link a connector with an API key
Source: https://docs.pinecone.io/api-reference/connectors/link-a-connector-with-an-api-key

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/nexus_2026-07.oas.yaml post /connectors/keys/{provider}



# List a context's connectors (with per-context enabled flag)
Source: https://docs.pinecone.io/api-reference/connectors/list-a-contexts-connectors-with-per-context-enabled-flag

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/nexus_2026-07.oas.yaml get /contexts/{slug}/connectors



# List the project's linked connectors
Source: https://docs.pinecone.io/api-reference/connectors/list-the-projects-linked-connectors

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/nexus_2026-07.oas.yaml get /connectors



# Start the OAuth link flow for a provider
Source: https://docs.pinecone.io/api-reference/connectors/start-the-oauth-link-flow-for-a-provider

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/nexus_2026-07.oas.yaml get /connectors/oauth/{provider}/start
Returns an `authorize_url` for the user to open in a browser. The connector is persisted by the provider's OAuth redirect callback once the user approves access.



# Unlink a connector
Source: https://docs.pinecone.io/api-reference/connectors/unlink-a-connector

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/nexus_2026-07.oas.yaml delete /connectors/{id}



# Create a context
Source: https://docs.pinecone.io/api-reference/contexts/create-a-context

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/nexus_2026-07.oas.yaml post /contexts
The context is created empty and is not queryable until you import sources and curate them (curate is explicit — there is no auto-curate). Optionally seed a `manifest`. A `work` context is the exception: it is queryable from day zero and is built from traces of work rather than source documents.



# Delete a context (and its Pinecone indexes)
Source: https://docs.pinecone.io/api-reference/contexts/delete-a-context-and-its-pinecone-indexes

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/nexus_2026-07.oas.yaml delete /contexts/{slug}



# Estimate the token + time cost of curating the in-progress manifest
Source: https://docs.pinecone.io/api-reference/contexts/estimate-the-token-+-time-cost-of-curating-the-in-progress-manifest

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/nexus_2026-07.oas.yaml post /contexts/{slug}/profile
Spins up the `profile` runtime to estimate the token + time cost of curating the sources under the in-progress manifest (sent in the request body), returned as the task's `output` (see `ProfileEstimateOutput`). Persists nothing; the console polls it for the Design-page cost box. Body is optional.



# Fork a context (copy manifest into a fresh target)
Source: https://docs.pinecone.io/api-reference/contexts/fork-a-context-copy-manifest-into-a-fresh-target

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/nexus_2026-07.oas.yaml post /contexts/{slug}/fork
Copies the source context's manifest and lifecycle metadata onto an **already-created** target context in the same project, so the target's query and curate gates pass. It does not create the target — create it first with `POST /contexts`. The target's index stays empty until curated. The source must have been optimized (`last_optimized_at` set) and must not be optimizing.



# Get a context
Source: https://docs.pinecone.io/api-reference/contexts/get-a-context

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/nexus_2026-07.oas.yaml get /contexts/{slug}



# List contexts (newest first, with stats)
Source: https://docs.pinecone.io/api-reference/contexts/list-contexts-newest-first-with-stats

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/nexus_2026-07.oas.yaml get /contexts



# Per-context task statistics
Source: https://docs.pinecone.io/api-reference/contexts/per-context-task-statistics

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/nexus_2026-07.oas.yaml get /contexts/{slug}/tasks/stats



# Run the Design-flow explore agent (propose a manifest)
Source: https://docs.pinecone.io/api-reference/contexts/run-the-design-flow-explore-agent-propose-a-manifest

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/nexus_2026-07.oas.yaml post /contexts/{slug}/explore
Inspects the uploaded source and proposes manifest-template matches, returned in the task's `output` (see `ExploreOutput`). Persists nothing on the index — review the proposal, then apply it via the manifest update + a forced curate. Body is optional.



# Trigger an on-demand self-tuning optimize
Source: https://docs.pinecone.io/api-reference/contexts/trigger-an-on-demand-self-tuning-optimize

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/nexus_2026-07.oas.yaml post /contexts/{slug}/optimize
Tunes the manifest from real query traffic and chains a forced re-curate. A body is required but every field in it is optional, so `{}` is valid — and a no-op when no `candidate_queries` are supplied. The context must have been curated, and only one optimize runs at a time.



# Update a context
Source: https://docs.pinecone.io/api-reference/contexts/update-a-context

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/nexus_2026-07.oas.yaml put /contexts/{slug}
All fields optional; absent leaves untouched. Empty string clears description/guide; `{}` clears the manifest back to defaults. A supplied manifest is validated against the manifest schema.



# Drop named sources from the index + ledger
Source: https://docs.pinecone.io/api-reference/curation/drop-named-sources-from-the-index-+-ledger

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/nexus_2026-07.oas.yaml post /contexts/{slug}/curate/delete-sources



# Get the curation ledger
Source: https://docs.pinecone.io/api-reference/curation/get-the-curation-ledger

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/nexus_2026-07.oas.yaml get /contexts/{slug}/curate
The full ledger: per-source hashes, edges, corpus groups, chunk-id lineage, version pin, reclaim intents, pointers, and glossary. This pays an O(corpus) chunk-id-lineage read — use `GET /contexts/{slug}/curate/version/pin` on the per-turn path.



# (Re)build the context's index from its sources
Source: https://docs.pinecone.io/api-reference/curation/rebuild-the-contexts-index-from-its-sources

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/nexus_2026-07.oas.yaml post /contexts/{slug}/curate
Curate the staged sources under the active manifest. **Required before querying** — there is no auto-curate. Body is optional. Set `force: true` to do a full rebuild (use after editing the manifest); the default is an incremental curate. Search contexts only — a work context builds via `work`/`groom` instead.



# Knowledge file/dir/size counts
Source: https://docs.pinecone.io/api-reference/knowledge/knowledge-filedirsize-counts

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/nexus_2026-07.oas.yaml get /contexts/{slug}/knowledge/stats



# List curated knowledge (root)
Source: https://docs.pinecone.io/api-reference/knowledge/list-curated-knowledge-root

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/nexus_2026-07.oas.yaml get /contexts/{slug}/knowledge/list



# List curated knowledge under a path
Source: https://docs.pinecone.io/api-reference/knowledge/list-curated-knowledge-under-a-path

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/nexus_2026-07.oas.yaml get /contexts/{slug}/knowledge/list/{path}



# Read a curated knowledge file (raw bytes)
Source: https://docs.pinecone.io/api-reference/knowledge/read-a-curated-knowledge-file-raw-bytes

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/nexus_2026-07.oas.yaml get /contexts/{slug}/knowledge/read/{path}



# Get the context's manifest
Source: https://docs.pinecone.io/api-reference/manifest/get-the-contexts-manifest

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/nexus_2026-07.oas.yaml get /contexts/{slug}/manifest
The context's pinned manifest document. A context with no pinned manifest returns `{}` — the runtime fills defaults. Writes go through the `manifest` field on `PUT /contexts/{slug}`.



# List the built-in manifest templates
Source: https://docs.pinecone.io/api-reference/manifest/list-the-built-in-manifest-templates

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/nexus_2026-07.oas.yaml get /manifest/templates
The catalog the console seeds new contexts from.



# Get the active project
Source: https://docs.pinecone.io/api-reference/project/get-the-active-project

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/nexus_2026-07.oas.yaml get /project



# Project-wide task stats
Source: https://docs.pinecone.io/api-reference/project/project-wide-task-stats

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/nexus_2026-07.oas.yaml get /stats
Aggregate task counters across the whole project (all contexts), broken down by state and workflow. The per-context equivalent is `GET /contexts/{slug}/tasks/stats`.



# Cancel an in-progress query turn
Source: https://docs.pinecone.io/api-reference/query/cancel-an-in-progress-query-turn

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/nexus_2026-07.oas.yaml post /queries/{id}/cancel
Idempotent — an already-terminal query is returned unchanged. On success the turn's `status` becomes `cancelled`.



# Delete a session and its queries
Source: https://docs.pinecone.io/api-reference/query/delete-a-session-and-its-queries

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/nexus_2026-07.oas.yaml delete /sessions/{id}



# Fetch one query (turn)
Source: https://docs.pinecone.io/api-reference/query/fetch-one-query-turn

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/nexus_2026-07.oas.yaml get /queries/{id}



# Fetch the recorded trace for a query turn
Source: https://docs.pinecone.io/api-reference/query/fetch-the-recorded-trace-for-a-query-turn

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/nexus_2026-07.oas.yaml get /queries/{id}/trace
The per-turn debug trace (steps, tool calls, strategy, cost, rollup). Trace persistence is unconditional — every turn lands a trace blob — so this is available once the turn is terminal.



# Get a session with its queries (conversation order)
Source: https://docs.pinecone.io/api-reference/query/get-a-session-with-its-queries-conversation-order

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/nexus_2026-07.oas.yaml get /sessions/{id}



# List project-wide query sessions (newest first)
Source: https://docs.pinecone.io/api-reference/query/list-project-wide-query-sessions-newest-first

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/nexus_2026-07.oas.yaml get /sessions



# List the selectable query models
Source: https://docs.pinecone.io/api-reference/query/list-the-selectable-query-models

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/nexus_2026-07.oas.yaml get /models
The model catalog the `model` field on `POST /query` draws from. Returns the default model, every catalog entry, the tier → model-id map, per-phase defaults, and the curate-capable model ids. Only entries with `available: true` are selectable (others are coming soon and rejected with `400`).



# Record thumbs-up/down feedback on a query turn
Source: https://docs.pinecone.io/api-reference/query/record-thumbs-updown-feedback-on-a-query-turn

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/nexus_2026-07.oas.yaml post /queries/{id}/feedback



# Run one KnowQL query turn
Source: https://docs.pinecone.io/api-reference/query/run-one-knowql-query-turn

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/nexus_2026-07.oas.yaml post /query
Send `ask` (the natural-language question) and, when starting a new session, a `scope` of 1–10 contexts. Continue an existing session with `session_id` or `previous_query_id`. Scoped search contexts must be curated (work contexts are queryable immediately), and a scope may not mix work and search contexts.

`stream` and `background` are mutually exclusive. With `background: true` the API returns `202` with an `in_progress` query and the client polls `GET /queries/{id}`. With `stream: true` the API emits an SSE stream whose `event:` names are the event `type` (`response.created`, `response.step`, `response.output_text.delta`, `response.turn_rollup`, `response.synthesis`, `response.trace`, and a terminal `response.completed` / `response.failed` / `response.cancelled`), followed by a final `query` event carrying the full query object. Read the answer from `output[].content[].text`.



# Stream a query turn's events (SSE)
Source: https://docs.pinecone.io/api-reference/query/stream-a-query-turns-events-sse

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/nexus_2026-07.oas.yaml get /queries/{id}/events
Server-sent event stream of the turn's events as they land — the same `type`-named events POST /query emits with `stream: true`, but as a standalone, resumable subscription. Reconnect with `Last-Event-ID` to replay from where the stream dropped.



# Delete a source file
Source: https://docs.pinecone.io/api-reference/source-files/delete-a-source-file

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/nexus_2026-07.oas.yaml delete /contexts/{slug}/source/delete/{path}



# Flat manifest of source files (path, size, last_modified)
Source: https://docs.pinecone.io/api-reference/source-files/flat-manifest-of-source-files-path-size-last_modified

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/nexus_2026-07.oas.yaml get /contexts/{slug}/source/manifest
Flat source-object inventory used to render the source page without walking the tree. Excludes the `_inbox/` staging directory.



# Import source documents from a project connector
Source: https://docs.pinecone.io/api-reference/source-files/import-source-documents-from-a-project-connector

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/nexus_2026-07.oas.yaml post /contexts/{slug}/import
Pull source documents from a linked project connector (Box, ...) into the context. Supply either `folder` or `files`. Stages the source only — curate explicitly before querying.



# List the source file tree (root)
Source: https://docs.pinecone.io/api-reference/source-files/list-the-source-file-tree-root

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/nexus_2026-07.oas.yaml get /contexts/{slug}/source/list



# List the source file tree under a path
Source: https://docs.pinecone.io/api-reference/source-files/list-the-source-file-tree-under-a-path

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/nexus_2026-07.oas.yaml get /contexts/{slug}/source/list/{path}



# Read a source file (raw bytes)
Source: https://docs.pinecone.io/api-reference/source-files/read-a-source-file-raw-bytes

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/nexus_2026-07.oas.yaml get /contexts/{slug}/source/read/{path}



# Source file/dir/size counts
Source: https://docs.pinecone.io/api-reference/source-files/source-filedirsize-counts

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/nexus_2026-07.oas.yaml get /contexts/{slug}/source/stats
Aggregate counts. Under preview mode the response also carries the per-context quota (`max_files_per_context`, `max_bytes_per_context`, `used_files`, `used_bytes`); those fields are absent otherwise.



# Upload a source file or archive
Source: https://docs.pinecone.io/api-reference/source-files/upload-a-source-file-or-archive

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/nexus_2026-07.oas.yaml post /contexts/{slug}/import/upload
One file per request, max 2 GiB. Archives (`.zip`, `.tar`, `.tar.gz`, `.tgz`) are expanded by the import runtime. Stages the source only — it does not index anything. Curate explicitly with `POST /contexts/{slug}/curate` before querying.



# Delete a task file
Source: https://docs.pinecone.io/api-reference/task-files/delete-a-task-file

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/nexus_2026-07.oas.yaml delete /tasks/{id}/files/delete/{path}



# List a task's files under a path
Source: https://docs.pinecone.io/api-reference/task-files/list-a-tasks-files-under-a-path

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/nexus_2026-07.oas.yaml get /tasks/{id}/files/list/{path}



# List a task's working-directory files
Source: https://docs.pinecone.io/api-reference/task-files/list-a-tasks-working-directory-files

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/nexus_2026-07.oas.yaml get /tasks/{id}/files/list



# Read a task file (raw bytes)
Source: https://docs.pinecone.io/api-reference/task-files/read-a-task-file-raw-bytes

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/nexus_2026-07.oas.yaml get /tasks/{id}/files/read/{path}
Serves from the live container while the task runs, and from the archived blob store afterwards. This is how a finished pack's `<slug>.context.zip` is downloaded.



# Stat a task file
Source: https://docs.pinecone.io/api-reference/task-files/stat-a-task-file

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/nexus_2026-07.oas.yaml get /tasks/{id}/files/metadata/{path}



# Cancel/terminate a task
Source: https://docs.pinecone.io/api-reference/tasks/cancelterminate-a-task

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/nexus_2026-07.oas.yaml delete /tasks/{id}
Body is optional. Max body 1 MiB.



# Get a task (with steps)
Source: https://docs.pinecone.io/api-reference/tasks/get-a-task-with-steps

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/nexus_2026-07.oas.yaml get /tasks/{id}



# List tasks (project-wide, paginated)
Source: https://docs.pinecone.io/api-reference/tasks/list-tasks-project-wide-paginated

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/nexus_2026-07.oas.yaml get /tasks



# Live token + runtime stats for a task
Source: https://docs.pinecone.io/api-reference/tasks/live-token-+-runtime-stats-for-a-task

https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/nexus_2026-07.oas.yaml get /tasks/{id}/stats



# 2022 releases
Source: https://docs.pinecone.io/assistant-release-notes/2022

Pinecone release notes for 2022: new features, improvements, and API changes.

## December 22, 2022

#### Pinecone is now available in Google Cloud Marketplace

You can now [sign up for Pinecone billing through Google Cloud Marketplace](/guides/organizations/manage-billing/upgrade-billing-plan).

## December 6, 2022

#### Organizations are generally available

Pinecone now features [organizations](/guides/organizations/understanding-organizations), which allow one or more users to control billing and project settings across multiple projects owned by the same organization.

#### p2 pod type is generally available

The [p2 pod type](/guides/index-data/indexing-overview#p2-pods) is now generally available and ready for production workloads. p2 pods are now available in the Starter plan and support the [dotproduct distance metric](/guides/index-data/create-an-index#dotproduct).

#### Performance improvements

* [Bulk vector\_deletes](/guides/index-data/upsert-data/#deleting-vectors) are now up to 10x faster in many circumstances.
* [Creating collections](/guides/manage-data/back-up-an-index) is now faster.

## October 31, 2022

#### Hybrid search (Early access)

Pinecone now supports keyword-aware semantic search with the new hybrid search indexes and endpoints. Hybrid search enables improved relevance for semantic search results by combining them with keyword search.

This is an **early access** feature and is available only by [signing up](https://www.pinecone.io/hybrid-search-early-access/).

## October 17, 2022

#### Status page

The new [Pinecone Status Page](https://status.pinecone.io/) displays information about the status of the Pinecone service, including the status of individual cloud regions and a log of recent incidents.

## September 16, 2022

#### Public collections

You can now create indexes from public collections, which are collections containing public data from real-world data sources. Currently, public collections include the Glue - SSTB collection, the TREC Question classification collection, and the SQuAD collection.

## August 16, 2022

#### Collections (Public preview)("Beta")

You can now \[make static copies of your index]\(/guides/manage-data/back-up-an-index using collections]\(/guides/manage-data/back-up-an-index#pod-based-index-backups-using-collections). After you create a collection from an index, you can create a new index from that collection. The new index can use any pod type and any number of pods. Collections only consume storage.

This is a **public preview** feature and is not appropriate for production workloads.

#### Vertical scaling

You can now [change the size of the pods](/guides/indexes/pods/scale-pod-based-indexes#increase-pod-size) for a live index to accommodate more vectors or queries without interrupting reads or writes. The p1 and s1 pod types are now available in [4 different sizes](/guides/index-data/indexing-overview/#pods-pod-types-and-pod-sizes): `1x`, `2x`, `4x`, and `8x`. Capacity and compute per pod double with each size increment.

#### p2 pod type (Public preview)("Beta")

The new [p2 pod type](/guides/index-data/indexing-overview/#p2-pods) provides search speeds of around 5ms and throughput of 200 queries per second per replica, or approximately 10x faster speeds and higher throughput than the p1 pod type, depending on your data and network conditions.

This is a **public preview** feature and is not appropriate for production workloads.

#### Improved p1 and s1 performance

The [s1](/guides/index-data/indexing-overview/#s1-pods) and [p1](/guides/index-data/indexing-overview/#p1-pods) pod types now offer approximately 50% higher query throughput and 50% lower latency, depending on your workload.

## July 26, 2022

You can now specify a [metadata filter](/guides/index-data/indexing-overview#metadata/) to get results for a subset of the vectors in your index by calling [describe\_index\_stats](/reference/api/2024-07/control-plane/describe_index) with a [filter](/reference/api/2024-07/control-plane/describe_index#!path=filter\&t=request) object.

The `describe_index_stats` operation now uses the `POST` HTTP request type. The `filter` parameter is only accepted by `describe_index_stats` calls using the `POST` request type. Calls to `describe_index_stats` using the `GET` request type are now deprecated.

## July 12, 2022

#### Pinecone Console Guided Tour

You can now choose to follow a guided tour in the [Pinecone console](https://app.pinecone.io). This interactive tutorial walks you through creating your first index, upserting vectors, and querying your data. The purpose of the tour is to show you all the steps you need to start your first project in Pinecone.

## June 24, 2022

#### Updated response codes

The [create\_index](/reference/api/2024-07/control-plane/create_index), [delete\_index](/reference/api/2024-07/control-plane/delete_index), and `scale_index` operations now use more specific HTTP response codes that describe the type of operation that succeeded.

## June 7, 2022

#### Selective metadata indexing

You can now store more metadata and more unique metadata values! [Select which metadata fields you want to index for filtering](/guides/indexes/pods/manage-pod-based-indexes#selective-metadata-indexing) and which fields you only wish to store and retrieve. When you index metadata fields, you can filter vector search queries using those fields. When you store metadata fields without indexing them, you keep memory utilization low, especially when you have many unique metadata values, and therefore can fit more vectors per pod.

#### Single-vector queries

You can now [specify a single query vector using the vector input](/reference/api/2024-07/data-plane/query/#!path=vector\&t=request). We now encourage all users to query using a single vector rather than a batch of vectors, because batching queries can lead to long response messages and query times, and single queries execute just as fast on the server side.

#### Query by ID

You can now [query your Pinecone index using only the ID for another vector](/reference/api/2024-07/data-plane/query/#!path=id\&t=request). This is useful when you want to search for the nearest neighbors of a vector that is already stored in Pinecone.

#### Improved index fullness accuracy

The index fullness metric in [describe\_index\_stats()](/reference/api/2024-07/control-plane/describe_index#!c=200\&path=indexFullness\&t=response) results is now more accurate.

## April 25, 2022

#### Partial updates (Public preview)

You can now perform a partial update by ID and individual value pairs. This allows you to update individual metadata fields without having to upsert a matching vector or update all metadata fields at once.

#### New metrics

Users on all plans can now see metrics for the past one (1) week in the Pinecone console. Users on the Enterprise plan now have access to the following metrics via the [Prometheus metrics endpoint](/guides/production/monitoring/):

* `pinecone_vector_count`
* `pinecone_request_count_total`
* `pinecone_request_error_count_total`
* `pinecone_request_latency_seconds`
* `pinecone_index_fullness` (Public preview)

**Note:** The accuracy of the `pinecone_index_fullness` metric is improved. This may result in changes from historic reported values. This metric is in public preview.

#### Spark Connector

Spark users who want to manage parallel upserts into Pinecone can now use the [official Spark connector for Pinecone](https://github.com/pinecone-io/spark-pinecone#readme) to upsert their data from a Spark dataframe.

#### Support for Boolean and float metadata in Pinecone indexes

You can now add `Boolean` and `float64` values to [metadata JSON objects associated with a Pinecone index.](/guides/index-data/indexing-overview#metadata)

#### New state field in describe\_index results

The [describe\_index](/reference/api/2024-07/control-plane/describe_index/) operation results now contain a value for `state`, which describes the state of the index. The possible values for `state` are `Initializing`, `ScalingUp`, `ScalingDown`, `Terminating`, and `Ready`.

##### Delete by metadata filter

The [Delete](/reference/api/2024-07/data-plane/delete/) operation now supports filtering my metadata.


# 2023 releases
Source: https://docs.pinecone.io/assistant-release-notes/2023

Pinecone release notes for 2023: new features, improvements, and API changes.

## December 2023

### Features

* The free Starter plan now supports up to 100 namespaces. [Namespaces](/guides/index-data/indexing-overview#namespaces) let you partition vectors within an index to speed up queries or comply with [multitenancy](/guides/index-data/implement-multitenancy) requirements.

## November 2023

### Features

* The new [Pinecone AWS Reference Architecture](https://github.com/pinecone-io/aws-reference-architecture-pulumi/tree/main) is an open-source, distributed system that performs vector-database-enabled semantic search over Postgres records. You can use it as a learning resource or as a starting point for high-scale use cases.

### SDKs

* [Canopy](https://github.com/pinecone-io/canopy/blob/main/README.md) is a new open-source Retrieval Augmented Generation (RAG) framework and context engine built on top of Pinecone. It enables you to start chatting with your documents or text data with a few simple commands.\
  The latest version of the Canopy SDK (v0.2.0) adds support for OpenAI SDK v1.2.3. See the [release notes](https://github.com/pinecone-io/canopy/releases/tag/V0.2.0) in GitHub for more details.

### Billing

* Pinecone is now registered to collect Value Added Tax (VAT) or Goods and Services Tax (GST) for accounts based in various global regions. If applicable, add your VAT or GST number to your account under **Settings > Billing**.

### October 2023

### Features

* [Collections](/guides/manage-data/back-up-an-index#pod-based-index-backups-using-collections) are now generally available (GA).

### Regions

* Pinecone Azure support via the [‘eastus-azure\` region](/guides/projects/understanding-projects#project-environments) is now generally available (GA).

### SDKs

* The latest version of our Node SDK is v1.1.2. See the [release notes](https://github.com/pinecone-io/pinecone-ts-client/releases/tag/v1.1.2) in GitHub for more details.

### Console

* The Index Browser is now available in the console. This allows you to preview, query, and filter by metadata directly from the console. The Index Browser can be found within the index detail page.
* We’re improved the design of our metrics page to include new charts for record and error count plus additional latencies (p90, p99) to help triage and understand issues.

### Integrations

* Knowledge Base for Amazon Bedrock is now available in private preview. Integrate your enterprise data via retrieval augmented generation (RAG) when building search and GenAI applications. [Learn more](https://www.pinecone.io/blog/amazon-bedrock-integration/).
* Pinecone Sink Connector for Confluent is now available in public preview. Gain access to data streams from across your business to build a real-time knowledge base for your AI applications. [Learn more](https://www.pinecone.io/confluent-integration).

### Billing

* You can now [sign up for Pinecone billing through Microsoft Marketplace](/guides/organizations/manage-billing/upgrade-billing-plan).

### Privacy

* Pinecone is now HIPAA compliant across all of our cloud providers (AWS, Azure, and GCP).

## September 11, 2023

Pinecone Azure support via the [eastus-azure region](/guides/projects/understanding-projects#project-environments) is now generally available (GA).

## August 14, 2023

Pinecone now supports deploying projects to Azure using the new [eastus-azure region](/guides/projects/understanding-projects#project-environments). This is a public preview environment, so test thoroughly before deploying to production.

## June 21, 2023

The new `gcp-starter` region is now in public preview. This region has distinct limitations from other Starter Plan regions. `gcp-starter` is the default region for some new users.

## April 26, 2023

[Indexes in the starter plan](/guides/index-data/indexing-overview#starter-plan) now support approximately 100,000 1536-dimensional embeddings with metadata. Capacity is proportional for other dimensionalities.

## April 3, 2023

Pinecone now supports [new US and EU cloud regions](/guides/projects/understanding-projects#project-environments).

## March 21, 2023

Pinecone now supports SSO on some Enterprise plans. [Contact Support](https://app.pinecone.io/organizations/-/settings/support) to set up your integration.

## March 1, 2023

Pinecone now supports [40kb of metadata per vector](/guides/index-data/indexing-overview#metadata#supported-metadata-size).

## February 22, 2023

#### Sparse-dense embeddings are now in public preview.

Pinecone now supports [vectors with sparse and dense values](/guides/search/hybrid-search#use-a-single-index-for-dense-and-sparse-vectors). To use sparse-dense embeddings in Python, upgrade to Python SDK version 2.2.0.

#### Pinecone Python SDK version 2.2.0 is available

Python SDK version 2.2.0 with support for sparse-dense embeddings is now available on [GitHub](https://github.com/pinecone-io/pinecone-python-client) and [PYPI](https://pypi.org/project/pinecone-client/2.2.0/).

## February 15, 2023

#### New Node.js SDK is now available in public preview

You can now try out our new [Node.js SDK for Pinecone](https://sdk.pinecone.io/typescript/).

## February 14, 2023

#### New usage reports in the Pinecone console

You can now monitor your current and projected Pinecone usage with the [**Usage** dashboard](/guides/manage-cost/monitor-usage-and-costs).

## January 31, 2023

#### Pinecone is now available in AWS Marketplace

You can now [sign up for Pinecone billing through Amazon Web Services Marketplace](/guides/organizations/manage-billing/upgrade-billing-plan).

## January 3, 2023

#### Pinecone Python SDK version 2.1.0 is now available on GitHub.

The [latest release of the Python SDK](https://github.com/pinecone-io/pinecone-python-client/releases/tag/2.1.0) makes the following changes:

* Fixes "Connection Reset by peer" error after long idle periods
* Adds typing and explicit names for arguments in all client operations
* Adds docstrings to all client operations
* Adds Support for batch upserts by passing `batch_size` to the upsert method
* Improves gRPC query results parsing performance


# 2024 releases
Source: https://docs.pinecone.io/assistant-release-notes/2024

Pinecone release notes for 2024: new features, improvements, and API changes.

## December 2024

<Update label="2024-12-23">
  ### Increased namespaces limit

  Customers on the [Standard plan](https://www.pinecone.io/pricing/) can now have up to 25,000 namespaces per index.
</Update>

<Update label="2024-12-19">
  ### Pinecone Assistant JSON mode and EU region deployment

  Pinecone Assistant can now [return a JSON response](/guides/assistant/chat-with-assistant#json-response).

  ***

  You can now [create an assistant](/reference/api/2025-01/assistant/create_assistant) in the `eu` region.
</Update>

<Update label="2024-12-17">
  ### Released Spark-Pinecone connector v1.2.0

  Released [`v1.2.0`](https://github.com/pinecone-io/spark-pinecone/releases/tag/v1.2.0) of the [Spark-Pinecone connector](/reference/tools/pinecone-spark-connector). This version introduces support for stream upserts with structured streaming. This enhancement allows users to seamlessly stream data into Pinecone for upsert operations.
</Update>

<Update label="2024-12-10">
  ### New integration with HoneyHive

  Added the [HoneyHive](/integrations/honeyhive) integration page.
</Update>

<Update label="2024-12-09">
  ### Released Python SDK v5.4.2

  Released [`v5.4.2`](https://github.com/pinecone-io/pinecone-python-client/releases/tag/v5.4.2) of the [Pinecone Python SDK](/reference/sdks/python/overview). This release adds a required keyword argument, `metric`, to the `query_namespaces` method. This change enables the SDK to merge results no matter how many results are returned.
</Update>

<Update label="2024-12-06">
  <img />

  ### Launch week: Pinecone Local

  Pinecone now offers Pinecone Local, an in-memory database emulator available as a Docker image. You can use Pinecone Local to [develop your applications locally](/guides/operations/local-development), or to [test your applications in CI/CD](/guides/production/automated-testing), without connecting to your Pinecone account, affecting production data, or incurring any usage or storage fees. Pinecone Local is in [public preview](/release-notes/feature-availability).
</Update>

<Update label="2024-12-05">
  ### Launch week: Enhanced security and access controls

  Support for [customer-managed encryption keys (CMEK)](/guides/production/configure-cmek) is now in [public preview](/release-notes/feature-availability).

  ***

  You can now [change API key permissions](/guides/projects/manage-api-keys#update-an-api-key).

  ***

  Private Endpoints are now in [general availability](/release-notes/feature-availability). Use Private Endpoints to [connect AWS PrivateLink](/guides/production/configure-private-endpoints) to Pinecone while keeping your VPC private from the public internet.

  ***

  [Audit logs](/guides/production/security-overview#audit-logs), now in early access, provide a detailed record of user and API actions that occur within the Pinecone platform.
</Update>

<Update label="2024-12-04">
  ### Launch week: `pinecone-rerank-v0` and `cohere-rerank-3.5` on Pinecone Inference

  Released [`pinecone-rerank-v0`](/guides/search/rerank-results#pinecone-rerank-v0), Pinecone's state of the art reranking model that out-performs competitors on widely accepted benchmarks. This model is in [public preview](/release-notes/feature-availability).

  ***

  Pinecone Inference now hosts [`cohere-rerank-3.5`](/guides/search/rerank-results#cohere-rerank-3.5), Cohere's leading reranking model.
</Update>

<Update label="2024-12-03">
  ### Launch week: Integrated Inference

  You can now use [embedding models](/guides/index-data/create-an-index#embedding-models) and [reranking models](/guides/search/rerank-results#reranking-models) hosted on Pinecone as an integrated part of upserting and searching.
</Update>

<Update label="2024-12-05">
  ### Released .NET SDK v2.1.0

  Released [`v2.1.0`](https://github.com/pinecone-io/pinecone-dotnet-client/releases/tag/2.1.0) of the [Pinecone .NET SDK](https://github.com/pinecone-io/pinecone-dotnet-client). This version adds support for [index tags](/guides/manage-data/manage-indexes#configure-index-tags) and introduces the `ClientOptions.IsTlsEnabled` property, which must be set to `false` for non-secure client connections.
</Update>

<Update label="2024-12-05">
  ### Improved batch deletion guidance

  Improved the guidance and example code for [deleting records in batches](/guides/manage-data/delete-data#delete-records-in-batches).
</Update>

<Update label="2024-12-02">
  ### Launch week: Released `pinecone-sparse-english-v0`

  Pinecone Inference now supports [`pinecone-sparse-english-v0`](/guides/search/rerank-results#pinecone-sparse-english-v0), Pinecone's sparse embedding model, which estimates the lexical importance of tokens by leveraging their context, unlike traditional retrieval models like BM25, which rely solely on term frequency. This model is in [public preview](/release-notes/feature-availability).
</Update>

## November 2024

<Update label="2024-11-30">
  ### Pinecone docs: New workflows and best practices

  Added typical [Pinecone Database and Pinecone Assistant workflows](/guides/get-started/overview) to the Docs landing page.

  ***

  Updated various examples to use the production best practice of [targeting an index by host](/guides/manage-data/target-an-index) instead of name.

  ***

  Updated the [Amazon Bedrock integration setup guide](/integrations/amazon-bedrock#setup-guide). It now utilizes Bedrock Agents.
</Update>

<Update label="2024-11-27">
  ### Released Java SDK v3.1.0

  Released [`v3.1.0`](https://github.com/pinecone-io/pinecone-java-client/releases/tag/v3.1.0) of the [Pinecone Java SDK](/reference/sdks/java/overview). This version introduces support for specifying a base URL for control and data plane operations.
</Update>

<Update label="2024-11-25">
  ### Pinecone Assistant: Context snippets and structured data files

  You can now [retrieve the context snippets](/guides/assistant/retrieve-context-snippets) that Pinecone Assistant uses to generate its responses. This data includes relevant chunks, relevancy scores, and references.

  ***

  You can now [upload JSON (.json) and Markdown (.md) files](/guides/assistant/manage-files#upload-a-local-file) to an assistant.
</Update>

<Update label="2024-11-14">
  ### Monthly spend alerts

  You can now set an organization-wide [monthly spend alert](/guides/manage-cost/manage-cost#set-a-monthly-spend-alert). When your organization's spending reaches the specified limit, you will receive an email notification.
</Update>

<Update label="2024-11-14">
  ### Released .NET SDK v2.0.0

  Released [`v2.0.0`](https://github.com/pinecone-io/pinecone-dotnet-client/releases/tag/2.0.0) of the [Pinecone .NET SDK](https://github.com/pinecone-io/pinecone-dotnet-client). This version uses the latest stable API version, `2024-10`, and adds support for [embedding](/reference/api/2025-01/inference/generate-embeddings), [reranking](https://docs.pinecone.io/reference/api/2025-01/inference/rerank), and [import](/guides/index-data/import-data). It also adds support for using the .NET SDK with [proxies](https://github.com/pinecone-io/pinecone-dotnet-client#configuring-http-proxy-for-both-control-and-data-plane-operations).
</Update>

<Update label="2024-11-13">
  ### Released Python SDK v5.4.0 and v5.4.1

  Released [`v5.4.0`](https://github.com/pinecone-io/pinecone-python-client/releases/tag/v5.4.0) and [`v5.4.1`](https://github.com/pinecone-io/pinecone-python-client/releases/tag/v5.4.1) of the [Pinecone Python SDK](/reference/sdks/python/overview). `v5.4.0` adds a `query_namespaces` utility method to [run a query in parallel across multiple namespaces](/reference/sdks/python/overview#query-across-namespaces) in an index and then merge the result sets into a single ranked result set with the `top_k` most relevant results. `v5.4.1` adds support for the `pinecone-plugin-inference` package required for some [integrated inference](/reference/api/introduction#inference) operations.
</Update>

<Update label="2024-11-08">
  ### Enabled CSV export of usage and costs

  You can now download a CSV export of your organization's usage and costs from the [Pinecone console](https://app.pinecone.io/organizations/-/settings/usage).
</Update>

<Update label="2024-11-07">
  ### Added Support chat in the console

  You can now chat with the Pinecone support bot and submit support requests directly from the [Pinecone console](https://app.pinecone.io/organizations/-/settings/support).
</Update>

<Update label="2024-11-05">
  ### Published Assistant quickstart guide

  Added an [Assistant quickstart](/guides/assistant/quickstart/sdk-quickstart).
</Update>

## October 2024

<Update label="2024-10-31">
  ### Cequence released updated Scala SDK

  [Cequence](https://github.com/cequence-io) released a new version of their community-supported [Scala SDK](https://github.com/cequence-io/pinecone-scala) for Pinecone. See their [blog post](https://cequence.io/blog/industry-know-how/introducing-the-pinecone-scala-client-async-intuitive-and-ready-for-action) for details.
</Update>

<Update label="2024-10-28">
  ### Added index tagging for categorization

  You can now [add index tags](/guides/manage-data/manage-indexes#configure-index-tags) to categorize and identify indexes.
</Update>

<Update label="2024-10-24">
  ### Released major SDK updates: Node.js, Go, Java, and Python

  Released [`v4.0.0`](https://github.com/pinecone-io/pinecone-ts-client/releases/tag/v4.0.0) of the [Pinecone Node.js SDK](/reference/sdks/node/overview). This version uses the latest stable API version, `2024-10`, and adds support for [reranking](/guides/search/rerank-results) and [import](/guides/index-data/import-data).

  ***

  Released [`v2.0.0`](https://github.com/pinecone-io/go-pinecone/releases/tag/v2.0.0) of the [Pinecone Go SDK](/reference/sdks/go/overview). This version uses the latest stable API version, `2024-10`, and adds support for [reranking](/guides/search/rerank-results) and [import](/guides/index-data/import-data).

  ***

  Released [`v3.0.0`](https://github.com/pinecone-io/pinecone-java-client/releases/tag/v3.0.0) of the [Pinecone Java SDK](/reference/sdks/java/overview). This version uses the latest stable API version, `2024-10`, and adds support for [embedding](/reference/api/2025-01/inference/generate-embeddings), [reranking](/reference/api/2025-01/inference/rerank), and [import](/guides/index-data/import-data).

  <Warning>
    `v3.0.0` also includes the following [breaking change](/reference/api/versioning#breaking-changes): The `control` class has been renamed `db_control`. Before upgrading to this version, be sure to update all relevant `import` statements to account for this change.

    For example, you would change `import org.openapitools.control.client.model.*;` to `import org.openapitools.db_control.client.model.*;`.
  </Warning>

  ***

  `v5.3.0` and `v5.3.1` of the [Pinecone Python SDK](/reference/sdks/python/overview) use the latest stable API version, `2024-10`. These versions were release previously.
</Update>

<Update label="2024-10-24">
  ### Pinecone API version `2024-10` is now the latest stable version

  `2024-10` is now the latest [stable version](/reference/api/versioning#release-schedule) of the [Database API](/reference/api/2024-10/data-plane/) and [Inference API](/reference/api/2024-10/inference/). For highlights, see [SDKs](#sdks) below.
</Update>

<Update label="2024-10-17">
  ### Pinecone Inference now available on the free Starter plan

  The free [Starter plan](https://www.pinecone.io/pricing/) now supports [reranking documents with Pinecone Inference](/guides/search/rerank-results).
</Update>

<Update label="2024-10-17">
  ### Customer-managed encryption keys (CMEK) in early access

  You can now use [customer-managed encryption keys (CMEK)](/guides/production/configure-cmek) to secure indexes within a Pinecone project. This feature is in [early access](/release-notes/feature-availability).
</Update>

<Update label="2024-10-07">
  ### Serverless index monitoring generally available

  Monitoring serverless indexes with [Prometheus](/guides/production/monitoring#monitor-with-prometheus) or [Datadog](/integrations/datadog) is now in [general availability](/release-notes/feature-availability).
</Update>

<Update label="2024-10-03">
  ### Data import from Amazon S3 in public preview

  You can now [import data](/guides/index-data/import-data) into an index from [Amazon S3](/guides/operations/integrations/integrate-with-amazon-s3). This feature is in [public preview](/release-notes/feature-availability).
</Update>

<Update label="2024-10-02">
  ### Chat and update features added to Assistant

  Added the [`chat_assistant`](/reference/api/2025-01/assistant/chat_assistant) endpoint to the Assistant API. It can be used to chat with your assistant, and get responses and citations back in a structured form.

  ***

  You can now add instructions when [creating](/guides/assistant/create-assistant) or [updating](/guides/assistant/manage-assistants#update-an-existing-assistant) an assistant. Instructions are a short description or directive for the assistant to apply to all of its responses. For example, you can update the instructions to reflect the assistant's role or purpose.

  ***

  You can now [update an existing assistant](/guides/assistant/manage-assistants#update-an-existing-assistant) with new instructions or metadata.
</Update>

## September 2024

<Update label="2024-09-25">
  Added the [Matillion](/integrations/matillion) integration page.
</Update>

<Update label="2024-09-23">
  Added guidance on using the Node.js SDK with [proxies](/reference/sdks/node/overview#proxy-configuration).
</Update>

<Update label="2024-09-19">
  Released [`v5.3.1`](https://github.com/pinecone-io/pinecone-python-client/releases/tag/v5.3.1) of the [Pinecone Python SDK](/reference/sdks/python/overview). This version adds a missing `python-dateutil` dependency.

  ***

  Released [`v1.1.1`](https://github.com/pinecone-io/go-pinecone/releases/tag/v1.1.1) of the [Pinecone Go SDK](/reference/sdks/go/overview). This version adds support for non-secure client connections.

  ***

  Released [`v2.1.0`](https://github.com/pinecone-io/pinecone-java-client/releases/tag/v2.1.0) of the [Pinecone Java SDK](/reference/sdks/java/overview). This version adds support for non-secure client connections.
</Update>

<Update label="2024-09-18">
  Released [`v5.3.0`](https://github.com/pinecone-io/pinecone-python-client/releases/tag/v5.3.0) of the [Pinecone Python SDK](/reference/sdks/python/overview). This version adds support for [import](/guides/index-data/import-data) operations. This feature is in [public preview](/release-notes/feature-availability).
</Update>

<Update label="2024-09-18">
  Added the `metrics_alignment` operation, which provides a way to [evaluate the correctness and completeness of a response](/guides/assistant/evaluate-answers) from a RAG system. This feature is in [public preview](/release-notes/feature-availability).

  ***

  When using Pinecone Assistant, you can now [choose an LLM](/guides/assistant/chat-with-assistant#choose-a-model-for-your-assistant) for the assistant to use and [filter the assistant's responses by metadata](/guides/assistant/chat-with-assistant#filter-chat-with-metadata).
</Update>

<Update label="2024-09-18">
  Added the [Datavolo](/integrations/datavolo) integration pages.
</Update>

<Update label="2024-09-17">
  Released [`v5.2.0`](https://github.com/pinecone-io/pinecone-python-client/releases/tag/v5.2.0) of the [Pinecone Python SDK](/reference/sdks/python/overview). This version adds support for [reranking documents with Pinecone Inference](/guides/search/rerank-results); it is no longer necessary to install the `pinecone-plugin-inference` package separately. This feature is in [public preview](/release-notes/feature-availability).
</Update>

<Update label="2024-09-16">
  [Prometheus monitoring for serverless indexes](/guides/production/monitoring#monitor-with-prometheus) is now in [public preview](/release-notes/feature-availability).
</Update>

<Update label="2024-09-12">
  Released [`v3.0.3`](https://github.com/pinecone-io/pinecone-ts-client/releases/tag/3.0.3) of the [Pinecone Node.js SDK](/reference/sdks/node/overview). This version removes extra logging and makes general internal enhancements.
</Update>

<Update label="2024-09-11">
  If you are upgrading from the [Starter plan](https://www.pinecone.io/pricing/), you can now connect your Pinecone organization to the [AWS Marketplace](/guides/organizations/manage-billing/upgrade-billing-plan), [Google Cloud Marketplace](/guides/organizations/manage-billing/upgrade-billing-plan), or [Microsoft Marketplace](/guides/organizations/manage-billing/upgrade-billing-plan) for billing purposes.
</Update>

<Update label="2024-09-11">
  Refreshed the navigation and overall visual interface of the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/).
</Update>

<Update label="2024-09-11">
  Added Go examples for [batch upserts](/guides/index-data/upsert-data#upsert-in-batches), [parallel upserts](/guides/index-data/upsert-data#send-upserts-in-parallel), and [deleting all records for a parent document](/guides/index-data/data-modeling#delete-chunks).
</Update>

## August 2024

<Update label="2024-08-28">
  Added the [Aryn](/integrations/aryn) integration page.
</Update>

<Update label="2024-08-28">
  Released [`v3.0.2`](https://github.com/pinecone-io/pinecone-ts-client/releases/tag/3.0.2) of the [Pinecone Node.js SDK](/reference/sdks/node/overview). This version removes a native Node utility function that was causing issues for users running in `Edge`. There are no downstream affects of its removal; existing code should not be impacted.
</Update>

<Update label="2024-08-27">
  Released [`v5.1.0`](https://github.com/pinecone-io/pinecone-python-client/releases/tag/v5.1.0) of the [Pinecone Python SDK](/reference/sdks/python/overview). With this version, the SDK can now be installed with `pip install pinecone` / `pip install "pinecone[grpc]"`. This version also includes a `has_index()` helper function to check if an index exists.

  ***

  Released [`v0.1.0`](https://github.com/pinecone-io/pinecone-rust-client/releases/tag/v0.1.0) and [`v0.1.1`](https://github.com/pinecone-io/pinecone-rust-client/releases/tag/v0.1.1) of the [Pinecone Rust SDK](https://github.com/pinecone-io/pinecone-rust-client). The Rust SDK is in "alpha" and is under active development. The SDK should be considered unstable and should not be used in production. Before a 1.0 release, there are no guarantees of backward compatibility between minor versions. See the [Rust SDK README](https://github.com/pinecone-io/pinecone-rust-client) for full installation instructions and usage examples.
</Update>

<Update label="2024-08-27">
  Released [`v1.0.0`](https://github.com/pinecone-io/pinecone-dotnet-client/releases/tag/1.0.0) of the [Pinecone .NET SDK](https://github.com/pinecone-io/pinecone-dotnet-client). For usage examples, see [our guides](/guides/get-started/quickstart) or the [GitHub README](https://github.com/pinecone-io/pinecone-dotnet-client).
</Update>

<Update label="2024-08-26">
  You can now [back up](/guides/manage-data/back-up-an-index) and [restore](/guides/manage-data/restore-an-index) serverless indexes. This feature is in public preview.

  ***

  Serverless indexes are now in [general availability on GCP and Azure](/guides/index-data/create-an-index#cloud-regions) for Standard and Enterprise plans.

  ***

  You can now deploy [serverless indexes](/guides/index-data/indexing-overview) in the `europe-west1` (Netherlands) region of GCP.
</Update>

<Update label="2024-08-26">
  Released [`v1.1.0`](https://github.com/pinecone-io/go-pinecone/releases/tag/v1.1.0) of the [Pinecone Go SDK](/reference/sdks/go/overview). This version adds support for generating embeddings via [Pinecone Inference](/reference/api/introduction#inference).
</Update>

<Update label="2024-08-21">
  Added the [Nexla](/integrations/nexla) integration page.
</Update>

<Update label="2024-08-15">
  [Pinecone Assistant](/guides/assistant/overview) is now in [public preview](/release-notes/feature-availability).
</Update>

<Update label="2024-08-13">
  The Pinecone Inference API now supports [reranking](https://docs.pinecone.io/guides/search/rerank-results). This feature is in [public preview](/release-notes/feature-availability).
</Update>

<Update label="2024-08-06">
  Released [`v1.0.0`](https://github.com/pinecone-io/go-pinecone/releases/tag/v1.0.0) of the [Pinecone Go SDK](/reference/sdks/go/overview). This version depends on Pinecone API version `2024-07` and includes the ability to [prevent accidental index deletion](/guides/manage-data/manage-indexes#configure-deletion-protection). With this version, the Go SDK is [officially supported](/troubleshooting/pinecone-support-slas) by Pinecone.
</Update>

<Update label="2024-08-05">
  Added the [Nuclia](/integrations/nuclia) integration page
</Update>

## July 2024

<Update label="2024-07-30">
  Added the [Redpanda](/integrations/redpanda) integration page.
</Update>

<Update label="2024-07-26">
  Updated the [Build a RAG chatbot](/guides/get-started/build-a-rag-chatbot) guide to use Pinecone Inference for generating embeddings.
</Update>

<Update label="2024-07-19">
  Added the ability to [prevent accidental index deletion](/guides/manage-data/manage-indexes#configure-deletion-protection).
</Update>

<Update label="2024-07-19">
  Released [`v5.0.0`](https://github.com/pinecone-io/pinecone-python-client/releases/tag/v5.0.0) of the [Pinecone Python SDK](/reference/sdks/python/overview). This version depends on Pinecone API version `2024-07` and includes the ability to [prevent accidental index deletion](/guides/manage-data/manage-indexes#configure-deletion-protection). Additionally, the `pinecone-plugin-inference` package required to [generate embeddings with Pinecone Inference](/reference/api/2025-01/inference/generate-embeddings) is now included by default; it is no longer necessary to install the plugin separately.

  ***

  Released [`v3.0.0`](https://github.com/pinecone-io/pinecone-ts-client/releases/tag/v3.0.0) of the [Pinecone Node.js SDK](/reference/sdks/node/overview). This version depends on Pinecone API version `2024-07` and includes the ability to [prevent accidental index deletion](/guides/manage-data/manage-indexes#configure-deletion-protection). Additionally, this version supports generating embeddings via [Pinecone Inference](/reference/api/2025-01/inference/generate-embeddings).

  ***

  Released [`v2.0.0`](https://github.com/pinecone-io/pinecone-java-client/releases/tag/v2.0.0) of the [Pinecone Java SDK](/reference/sdks/java/overview). This version depends on Pinecone API version `2024-07` and includes the ability to [prevent accidental index deletion](/guides/manage-data/manage-indexes#configure-deletion-protection). Additionally, this version includes the following **breaking changes**:

  * `createServerlessIndex()` now requires a new argument: `DeletionProtection.ENABLED` or `DeletionProtection.DISABLED`.
  * `configureIndex()` has been renamed `configurePodsIndex()`.

  For more details, see the [Java SDK v2.0.0 migration guide](https://github.com/pinecone-io/pinecone-java-client/blob/main/v2-migration.md).
</Update>

<Update label="2024-07-19">
  Released version `2024-07` of the [Database API](/reference/api/2024-07/data-plane/) and Inference API. This version includes the following highlights:

  * The [`create_index`](/reference/api/2024-07/control-plane/create_index) and [`configure_index`](/reference/api/2024-07/control-plane/configure_index) endpoints now support the `deletion_protection` parameter. Setting this parameter to `"enabled"` prevents an index from accidental deletion. For more details, see [Prevent index deletion](/guides/manage-data/manage-indexes#configure-deletion-protection).

  * The [`describe_index`](/reference/api/2024-07/control-plane/describe_index) and [`list_index`](/reference/api/2024-07/control-plane/list_indexes) responses now include the `deletion_protection` field. This field indicates whether deletion protection is enabled for an index.

  * The `spec.serverless.cloud` and `spec.serverless.region` parameters of [`create_index`](/reference/api/2024-07/control-plane/create_index) now support `gcp` / `us-central` and `azure` / `eastus2` as part of the serverless public preview on GCP and Azure.
</Update>

<Update label="2024-07-17">
  Serverless indexes are now in [public preview on Azure](/guides/index-data/create-an-index#cloud-regions) for Standard and Enterprise plans.
</Update>

<Update label="2024-07-10">
  Released [version 1.1.0](https://github.com/pinecone-io/spark-pinecone/releases/tag/v1.1.0) of the official Spark connector for Pinecone. In this release, you can now set a [source tag](/integrations/build-integration/attribute-usage-to-your-integration). Additionally, you can now [upsert records](/guides/index-data/upsert-data) with 40KB of metadata, increased from 5KB.
</Update>

<Update label="2024-07-01">
  Serverless indexes are now in [public preview on GCP](/guides/index-data/create-an-index#cloud-regions) for Standard and Enterprise plans.
</Update>

<Update label="2024-07-01">
  Added an introduction to [key concepts in Pinecone](/guides/get-started/concepts) and how they relate to each other.

  ***

  Added the [Twelve Labs](/integrations/twelve-labs) integration page.
</Update>

## June 2024

<Update label="2024-06-30">
  Added a [model gallery](/models/overview) with details and guidance on popular embedding and reranking models, including models hosted on Pinecone's infrastructure.
</Update>

<Update label="2024-06-28">
  Released [version 1.2.2](https://github.com/pinecone-io/pinecone-java-client/releases/tag/v1.2.2) of the Pinecone Java SDK. This release simplifies the proxy configuration process. It also fixes an issue where the user agent string was not correctly setup for gRPC calls. Now, if the source tag is set by the user, it is appended to the custom user agent string.
</Update>

<Update label="2024-06-27">
  You can now load a [sample dataset](/guides/data/use-sample-datasets) into a new project.

  ***

  Simplified the process for [migrating paid pod indexes to serverless](/guides/indexes/pods/migrate-a-pod-based-index-to-serverless).
</Update>

<Update label="2024-06-25">
  The [Assistant API](/guides/assistant/overview) is now in beta release.
</Update>

<Update label="2024-06-20">
  The [Inference API](/reference/api/introduction#inference) is now in public preview.
</Update>

<Update label="2024-06-18">
  Added a new [legal semantic search](https://docs.pinecone.io/examples/sample-apps/legal-semantic-search) sample app that demonstrates low-latency natural language search over a knowledge base of legal documents.
</Update>

<Update label="2024-06-17">
  Added the [Instill](/integrations/instill) integration page.
</Update>

<Update label="2024-06-07">
  Added the [Langtrace](/integrations/langtrace) integration page.
</Update>

<Update label="2024-06-06">
  Updated Python code samples to use the gRPC version of the [Python SDK](/reference/sdks/python/overview), which is more performant than the Python SDK that interacts with Pinecone via HTTP requests.
</Update>

<Update label="2024-06-06">
  Released [version 4.1.1](https://github.com/pinecone-io/pinecone-python-client/releases/tag/v4.1.1) of the Pinecone Python SDK. In this release, you can now use colons inside source tags. Additionally, the gRPC version of the Python SDK now allows retries of up to `MAX_MSG_SIZE`.
</Update>

<Update label="2024-06-05">
  The Enterprise [quota for namespaces per serverless index](/reference/api/database-limits#namespaces-per-serverless-index) has increased from 50,000 to 100,000.
</Update>

<Update label="2024-06-04">
  Added the [Fleak](/integrations/fleak) integration page.
</Update>

## May 2024

<Update label="2024-05-31">
  Released [version 1.2.1](https://github.com/pinecone-io/pinecone-java-client/releases/tag/v1.2.1) of the [Pinecone Java SDK](/reference/sdks/java/overview). This version fixes the error `Could Not Find NameResolverProvider` using uber jar.
</Update>

<Update label="2024-05-31">
  Added the [Gathr](/integrations/gathr) integration page.
</Update>

<Update label="2024-05-30">
  Released [version 1.1.0](https://github.com/pinecone-io/pinecone-java-client/releases/tag/v1.1.0) of the [Pinecone Java SDK](/reference/sdks/java/overview). This version adds the ability to [list record IDs with a common prefix](/guides/manage-data/list-record-ids#list-the-ids-of-records-with-a-common-prefix).
</Update>

<Update label="2024-05-29">
  Released version [1.2.0](https://github.com/pinecone-io/pinecone-java-client/releases/tag/v1.2.0) of the [Pinecone Java SDK](/reference/sdks/java/overview). This version adds the ability to [list all record IDs in a namespace](/guides/manage-data/list-record-ids#list-the-ids-of-all-records-in-a-namespace).
</Update>

<Update label="2024-05-29">
  Added the following integration pages:

  * [Apify](/integrations/apify)
  * [Context Data](/integrations/context-data)
  * [Estuary](/integrations/estuary)
  * [GitHub Copilot](/integrations/github-copilot)
  * [Jina](/integrations/jina)
  * [FlowiseAI](/integrations/flowise)
  * [OctoAI](/integrations/octoai)
  * [Streamnative](/integrations/streamnative)
  * [Traceloop](/integrations/traceloop)
  * [Unstructured](/integrations/unstructured)
  * [VoyageAI](/integrations/voyage)
</Update>

<Update label="2024-05-21">
  You can now use the `ConnectPopup` function to bypass the [**Connect** widget](/integrations/build-integration/connect-your-users-to-pinecone) and open the "Connect to Pinecone" flow in a popup. This can be used in an app or website for a seamless Pinecone signup and login process.
</Update>

<Update label="2024-05-16">
  Released [version 1.0.0](https://github.com/pinecone-io/spark-pinecone/releases/tag/v1.0.0) of the official Spark connector for Pinecone. In this release, you can now upsert records into [serverless indexes](/guides/index-data/indexing-overview).
</Update>

<Update label="2024-05-08">
  Pinecone now supports [AWS PrivateLink](/guides/production/configure-private-endpoints). Create and use [Private Endpoints](/guides/production/configure-private-endpoints#manage-private-endpoints) to connect AWS PrivateLink to Pinecone while keeping your VPC private from the public internet.
</Update>

<Update label="2024-05-01">
  Released [version 4.0.0](https://github.com/pinecone-io/pinecone-python-client/releases/tag/v4.0.0) of the Pinecone Python SDK. In this release, we are upgrading the `protobuf` dependency in our optional `grpc` extras from `3.20.3` to `4.25.3`. Significant performance improvements have been made with this update. This is a breaking change for users of the optional GRPC addon ([installed with `pinecone[grpc]`](https://github.com/pinecone-io/pinecone-python-client?tab=readme-ov-file#working-with-grpc-for-improved-performance)).
</Update>

## April 2024

<Update label="2024-04-30">
  * The docs now have a new AI chatbot. Use the search bar at the top of our docs to find related content across all of our resources.
  * We've updated the look and feel of our [example notebooks](/examples/notebooks) and [sample apps](/examples/sample-apps). A new sample app, [Namespace Notes](/examples/sample-apps/namespace-notes), a simple multi-tenant RAG app that uploads documents, has also been added.
</Update>

<Update label="2024-04-30">
  The free [Starter plan](https://www.pinecone.io/pricing/) now includes 1 project, 5 serverless indexes in the `us-east-1` region of AWS, and up to 2 GB of storage. Although the Starter plan has stricter [limits](/reference/api/database-limits) than other plans, you can [upgrade](/guides/organizations/manage-billing/upgrade-billing-plan) whenever you're ready.
</Update>

<Update label="2024-04-26">
  Pinecone now provides a [**Connect** widget](/integrations/build-integration/connect-your-users-to-pinecone) that can be embedded into an app, website, or Colab notebook for a seamless signup and login process.
</Update>

<Update label="2024-04-22">
  Added the [lifecycle policy of the Pinecone API](/release-notes/feature-availability), which describes the availability phases applicable to APIs, features, and SDK versions.
</Update>

<Update label="2024-04-22">
  As announced in January 2024, [control plane](/reference/api/2024-07/control-plane) operations like `create_index`, `describe_index`, and `list_indexes` now use a single global URL, `https://api.pinecone.io`, regardless of the cloud environment where an index is hosted. This is now in general availability. As a result, the legacy version of the API, which required regional URLs for control plane operations, is deprecated as of April 15, 2024 and will be removed in a future, to be announced, release.
</Update>

<Update label="2024-04-15">
  Added the [Terraform](/integrations/terraform) integration page.
</Update>

<Update label="2024-04-15">
  Released version 0.9.0 of the [Canopy SDK](https://github.com/pinecone-io/canopy/blob/main/README.md). This version adds support for OctoAI LLM and embeddings, and Qdrant as a supported knowledge base. See the [v0.9.0 release notes](https://github.com/pinecone-io/canopy/releases/tag/v0.9.0) in GitHub for more details.
</Update>

<Update label="2024-04-12">
  You can now deploy [serverless indexes](/guides/index-data/indexing-overview) in the `eu-west-1` region of AWS.
</Update>

<Update label="2024-04-12">
  Released version 1.0.0 of the [Pinecone Java SDK](/reference/sdks/java/overview). With this version, the Java SDK is [officially supported](/troubleshooting/pinecone-support-slas) by Pinecone. For full details on the release, see the [v1.0.0 release notes](https://github.com/pinecone-io/pinecone-java-client/releases/tag/v1.0.0) in GitHub. For usage examples, see [our guides](/guides/get-started/quickstart) or the [GitHub README](https://github.com/pinecone-io/pinecone-java-client). To migrate to v1.0.0 from version 0.8.x or below, see the [Java v1.0.0 migration guide](https://github.com/pinecone-io/pinecone-java-client/blob/main/v1-migration.md).
</Update>

## March 2024

<Update label="2024-03-31">
  Added a [Troubleshooting](https://docs.pinecone.io/troubleshooting/) section, which includes content on best practices, troubleshooting, and how to address common errors.

  ***

  Added an explanation of the [Pinecone serverless architecture](/guides/get-started/database-architecture), including descriptions of the high-level components and explanations of the distinct paths for writes and reads.

  ***

  Added [considerations for querying serverless indexes with metadata filters](/guides/index-data/indexing-overview#metadata#considerations-for-serverless-indexes).
</Update>

<Update label="2024-03-30">
  Released [version 3.2.2](https://github.com/pinecone-io/pinecone-python-client/releases/tag/v3.2) of the [Pinecone Python SDK](/reference/sdks/python/overview). This version fixes a minor issue introduced in v3.2.0 that resulted in a `DeprecationWarning` being incorrectly shown to users who are not passing in the deprecated `openapi_config` property. This warning can safely be ignored by anyone who is not preparing to upgrade.
</Update>

<Update label="2024-03-29">
  Released [version 3.2.0](https://github.com/pinecone-io/pinecone-python-client/releases/tag/v3.2.0) of the [Pinecone Python SDK](/reference/sdks/python/overview). This version adds four optional configuration properties that enable the use of Pinecone [via proxy](/reference/sdks/python/overview#proxy-configuration).
</Update>

<Update label="2024-03-28">
  Released [version 2.2.0](https://github.com/pinecone-io/pinecone-ts-client/releases/tag/v2.2.0) of the [Pinecone Node.js SDK](/reference/sdks/node/overview). This releases adds an optional `sourceTag` that you can set when constructing a Pinecone client to help Pinecone associate API activity to the specified source.
</Update>

<Update label="2024-03-27">
  Released version 0.4.1 of the [Pinecone Go SDK](/reference/sdks/go/overview). This version adds an optional `SourceTag` that you can set when constructing a Pinecone client to help Pinecone associate API activity to the specified source.

  ***

  Released version 2.2.0 of the [Pinecone Node.js SDK](/reference/sdks/node/overview).

  ***

  Released [version 0.4.1](https://github.com/pinecone-io/go-pinecone/releases/tag/v0.4.1) of the [Pinecone Go SDK](/reference/sdks/go/overview).
</Update>

<Update label="2024-03-25">
  Released version 3.2.1 of the [Pinecone Python SDK](/reference/sdks/python/overview). This version adds an optional `source_tag` that you can set when constructing a Pinecone client to help Pinecone associate API activity to the specified source. See the [v3.2.1 release notes](https://github.com/pinecone-io/pinecone-python-client/releases/tag/v3.2.1) in GitHub for more details.
</Update>

<Update label="2024-03-21">
  Released version 0.8.1 of the [Canopy SDK](https://github.com/pinecone-io/canopy/blob/main/README.md). This version includes bug fixes, the removal of an unused field for Cohere chat calls, and added guidance on creating a knowledge base with a specified record encoder when using the core library. See the [v0.8.1 release notes](https://github.com/pinecone-io/canopy/releases/tag/v0.8.1) in GitHub for more details.
</Update>

<Update label="2024-03-20">
  The [Pinecone console](https://app.pinecone.io) has a new look and feel, with a brighter, minimalist design; reorganized menu items for quicker, more intuitive navigation; and easy access to recently viewed indexes in the sidebar.

  ***

  When viewing the list of indexes in a project, you can now search indexes by index name; sort indexes alphabetically, by how recently they were viewed or created, or by status; and filter indexes by index type (serverless, pod-based, or starter).
</Update>

<Update label="2024-03-15">
  Released version 0.4.0 of the [Pinecone Go SDK](/reference/sdks/go/overview). This version is a comprehensive re-write and adds support for all current [Pinecone API operations](/reference/api/introduction).
</Update>

<Update label="2024-03-14">
  Fixed a bug that caused inaccurate index fullness reporting for some pod-based indexes on GCP.

  ***

  You can now deploy [serverless indexes](/guides/index-data/indexing-overview) in the `us-east-1` region of AWS.
</Update>

<Update label="2024-03-06">
  Released version 2.1.0 of the [Pinecone Node.js SDK](/reference/sdks/node/overview). This version adds support for [listing the IDs of records in a serverless index](/guides/manage-data/list-record-ids). You can list all records or just those with a common ID prefix.
</Update>

<Update label="2024-03-05">
  You can now [configure single single-on](/guides/production/configure-single-sign-on/okta) to manage your teams' access to Pinecone through any identity management solution with SAML 2.0 support, such as Okta. This feature is available on the [Enterprise plan](https://www.pinecone.io/pricing/) only.
</Update>

## February 2024

<Update label="2024-02-29">
  Updated the [Langchain integration guide](/integrations/langchain) to avoid a [namespace collision issue](/troubleshooting/pinecone-attribute-errors-with-langchain).
</Update>

<Update label="2024-02-27">
  The latest version of the [Canopy SDK](https://github.com/pinecone-io/canopy/blob/main/README.md) (v0.8.0) adds support for Pydantic v2. For applications depending on Pydantic v1, this is a breaking change; review the [Pydantic v1 to v2 migration guide](https://docs.pydantic.dev/latest/migration/) and make the necessary changes before upgrading. See the [Canopy SDK release notes](https://github.com/pinecone-io/canopy/releases/tag/v0.8.0) in GitHub for more details.
</Update>

<Update label="2024-02-23" description="SDK">
  The latest version of Pinecone's Python SDK (v3.1.0) adds support for [listing the IDs of records in a serverless index](/guides/manage-data/list-record-ids). You can list all records or just those with a [common ID prefix](/guides/index-data/data-modeling#use-structured-ids). See the [Python SDK release notes](https://github.com/pinecone-io/pinecone-python-client/releases/tag/v3.1.0) in GitHub for more details.
</Update>

<Update label="2024-02-22">
  Improved the docs for [setting up billing through the AWS Marketplace](/guides/organizations/manage-billing/upgrade-billing-plan) and [Google Cloud Marketplace](/guides/organizations/manage-billing/upgrade-billing-plan).
</Update>

<Update label="2024-02-16">
  It is now possible to convert a pod-based starter index to a serverless index. For organizations on the Starter plan, this requires upgrading to Standard or Enterprise; however, upgrading comes with \$100 in serverless credits, which will cover the cost of a converted index for some time.
</Update>

<Update label="2024-02-01">
  Added a [Llamaindex integration guide](/integrations/llamaindex) on building a RAG pipeline with LlamaIndex and Pinecone.
</Update>

## January 2024

<Update label="2024-01-31">
  The latest version of the [Canopy SDK](https://github.com/pinecone-io/canopy/blob/main/README.md) (v0.6.0) adds support for the new API mentioned above as well as namespaces, LLMs that do not have function calling functionality for query generation, and more. See the [release notes](https://github.com/pinecone-io/canopy/releases/tag/v0.6.0) in GitHub for more details.
</Update>

<Update label="2024-01-09">
  The latest versions of Pinecone's Python SDK (v3.0.0) and Node.js SDK (v2.0.0) support the new API. To use the new API, existing users must upgrade to the new client versions and adapt some code. For guidance, see the [Python SDK v3 migration guide](https://canyon-quilt-082.notion.site/Pinecone-Python-SDK-v3-0-0-Migration-Guide-056d3897d7634bf7be399676a4757c7b) and [Node.js SDK v2 migration guide](https://github.com/pinecone-io/pinecone-ts-client/blob/main/v2-migration.md).
</Update>

<Update label="2024-01-09">
  The Pinecone documentation is now versioned. The default "latest" version reflects the new Pinecone API. The "legacy" version reflects the previous API, which requires regional URLs for control plane operations and does not support serverless indexes.
</Update>

<Update label="2024-01-09">
  The [new Pinecone API](/reference/api) gives you the same great vector database but with a drastically improved developer experience. The most significant improvements include:

  * [Serverless indexes](/guides/index-data/indexing-overview): With serverless indexes, you don't configure or manage compute and storage resources. You just load your data and your indexes scale automatically based on usage. Likewise, you don't pay for dedicated resources that may sometimes lay idle. Instead, the pricing model for serverless indexes is consumption-based: You pay only for the amount of data stored and operations performed, with no minimums.

  * [Multi-region projects](/guides/projects/understanding-projects): Instead of choosing a cloud region for an entire project, you now [choose a region for each index](/guides/index-data/create-an-index#create-a-serverless-index) in a project. This makes it possible to consolidate related indexes in the same project, even when they are hosted in different regions.

  * [Global URL for control plane operations](/reference): Control plane operations like `create_index`, `describe_index`, and `list_indexes` now use a single global URL, `https://api.pinecone.io`, regardless of the cloud environment where an index is hosted. This simplifies the experience compared to the legacy API, where each environment has a unique URL.
</Update>


# 2025 releases
Source: https://docs.pinecone.io/assistant-release-notes/2025

Pinecone release notes for 2025: new features, improvements, and API changes.

## December 2025

<Update label="2025-12-29">
  ### Increased metadata limit for assistants

  The metadata field limit for assistants has been increased from 1KB to 16KB.

  Assistant metadata is a JSON object that you can use to store custom organizational data, tags, and attributes for your assistants. You can specify metadata when creating an assistant by including a `metadata` field in your request, or update it later using the update assistant endpoint.

  For more information, see [Create an assistant](/reference/api/latest/assistant/create_assistant) and [Manage assistants](/guides/assistant/manage-assistants).
</Update>

<Update label="2025-12-23">
  ### Test Pinecone at scale

  Added a new guide to help you [test Pinecone at production scale](/guides/get-started/test-at-scale). The guide describes how to create an index, import 10 million vectors, and then use Vector Search Bench (VSB) to capture performance metrics for 100,000 queries. To run this test, consider signing up for a [Standard plan trial](/guides/organizations/manage-billing/standard-trial).
</Update>

<Update label="2025-12-22">
  ### Pinecone Assistant now supports GPT-5

  Pinecone Assistant now supports the GPT-5 model. To use it, set `model` to `gpt-5` when [chatting with your assistant](/reference/api/latest/assistant/chat_assistant).

  For more information, see [Chat with Assistant](/guides/assistant/chat-with-assistant#choose-a-model) and [Chat through the OpenAI-compatible interface](/guides/assistant/chat-through-the-openai-compatible-interface#choose-a-model).
</Update>

<Update label="2025-12-12">
  ### Upgrade from Starter to Standard trial

  Organizations on the Starter plan can now upgrade to a Standard plan trial at any time. The Standard trial provides 21 days and \$300 in credits to test Pinecone at scale, with access to Standard plan features such as higher limits. For more information, see [Standard plan trial](/guides/organizations/manage-billing/standard-trial).
</Update>

<Update label="2025-12-07">
  ### Delete Assistant files while they are still processing

  You can now delete a file uploaded to an assistant while it is still processing. Previously, you had to wait for file processing to complete before you could delete a file.

  For more information, see [Manage files](/guides/assistant/manage-files).
</Update>

<Update label="2025-12-02">
  ### Annual commit discount

  In the Pinecone console, customers on Standard and Enterprise pay-as-you-go plans can now commit to an annual contract and receive a discount on usage. For more information, see [Understanding cost](/guides/manage-cost/understanding-cost#discounts).
</Update>

<Update label="2025-12-02">
  ### Increased instructions limit for assistants

  The maximum size for assistant instructions has been increased from 8 KB to 16 KB.

  Instructions are included in every chat API call. Longer instructions increase input token costs for each request and consume more of the LLM's context window, reducing available space for retrieved context and conversation history.

  For more information, see [Create an assistant](/reference/api/latest/assistant/create_assistant) and [Manage assistants](/guides/assistant/manage-assistants).
</Update>

<Update label="2025-12-01">
  ### Dedicated Read Nodes: now in public preview

  [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) is now in [public preview](/release-notes/feature-availability). Users on Standard and Enterprise plans can now create Dedicated Read Nodes indexes using the console and API.

  With Dedicated Read Nodes, you can provision read hardware for large, high-throughput indexes that require predictable, low latency.

  For more information, see [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes).
</Update>

## November 2025

<Update label="2025-11-19">
  ### Pinecone API version `2025-10` is now the latest stable version

  `2025-10` is now the latest [stable version](/reference/api/versioning#release-schedule) of the [Pinecone APIs](/reference/api/introduction). This version does not include any breaking changes, and provides the following new features:

  **[Dedicated read nodes](/guides/index-data/dedicated-read-nodes) (early access):**

  * The [Create an index](/reference/api/2025-10/control-plane/create_index) and [Configure index](/reference/api/2025-10/control-plane/configure_index) endpoints allow you to create and configure indexes that use dedicated read nodes. With dedicated read nodes, you can allocate dedicated hardware for read operations. This is useful for large, high-QPS indexes that require consistent, predictable low latency.
  * The [Describe an index](/reference/api/2025-10/control-plane/describe_index) endpoint now allows you to view information about a dedicated index: shards, replicas, and scaling status.

  **Namespace and metadata schema management:**

  * The [Create a namespace](/reference/api/2025-10/data-plane/createnamespace) endpoint allows you to create a namespace without upserting vectors. You can optionally configure a metadata schema when creating the namespace to pre-declare which metadata fields should be indexed for filtering.
  * The [List namespaces](/reference/api/2025-10/data-plane/listnamespaces) endpoint now supports filtering namespaces by prefix and returns the total count of matching namespaces.
  * The [Describe a namespace](/reference/api/2025-10/data-plane/describenamespace) endpoint allows you to view the metadata schema configuration for a namespace, including which fields are indexed for filtering.
  * The [Create an index](/reference/api/2025-10/control-plane/create_index) endpoint now allows you to specify a metadata schema at index creation time to pre-declare which metadata fields should be indexed for filtering across all namespaces.

  **Update and fetch by metadata:**

  * The [Update a vector](/reference/api/2025-10/data-plane/update) endpoint allows you to update metadata across multiple records in a namespace using a metadata filter expression, eliminating the need to update records individually by ID.
  * The [Fetch vectors by metadata](/reference/api/2025-10/data-plane/fetch_by_metadata) endpoint allows you to fetch vectors using metadata filters without knowing their vector IDs.

  **Enhanced sparse search:**

  * The [Search with text](/reference/api/2025-10/data-plane/search_records) endpoint now supports a `match_terms` parameter that allows you to specify terms that must be present in search results for sparse indexes.
</Update>

<Update label="2025-11-03">
  ### n8n quickstarts

  Added new quickstart options to create an n8n workflow that downloads files via HTTP and lets you chat with them using Pinecone and OpenAI.

  * [n8n quickstart for Pinecone Assistant](/guides/assistant/quickstart/n8n-quickstart)
  * [n8n quickstart for Pinecone Database](/guides/get-started/quickstart#n8n)
</Update>

<Update label="2025-11-03">
  ### Released Node.js SDK v6.1.3

  Released [`v6.1.3`](https://github.com/pinecone-io/pinecone-ts-client/releases/tag/v6.1.3) of the [Pinecone Node.js SDK](/reference/sdks/node/overview).

  This version of the SDK fixes a bug in `Assistant.listFiles()`. Previously, when passing a `filter` to `listFiles`, the top-level `metadata` object was not handled correctly. This caused the method to return all files, regardless of the filter.

  It's no longer necessary to provide a top-level `metadata` object. Instead, declare metadata fields directly in the `filter` object:

  * ✅ `const files = await assistant.listFiles({ filter: { document_type: 'manuscript' } });`
  * ❌ `const files = await assistant.listFiles({ filter: { metadata: { document_type: 'manuscript' } } });`

  If you're using the old syntax, update it so that your filter works correctly. For more information about listing the files associated with an assistant, see [Manage files](/guides/assistant/manage-files).
</Update>

## October 2025

<Update label="2025-10-30">
  ### Increased files per assistant on the Starter plan

  On the Starter plan, you can now upload up to 100 files to an assistant. Previously, the limit was 10 files.

  To learn more, see [Assistant limits](/guides/assistant/pricing-and-limits#assistant-limits).
</Update>

<Update label="2025-10-23">
  ### Enhanced monthly spend alerts

  You can now set multiple spend alerts to monitor your organization's monthly spending. These alerts notify designated recipients when spending reaches specified thresholds. The alerts automatically reset at the start of each monthly billing cycle.

  Additionally, to protect from unexpected cost increases, Pinecone sends an alert when spending exceeds double your previous month's invoice amount. While the alert threshold is fixed, you can modify which email addresses receive the alert and enable or disable the alert notifications.

  To learn more, see [Manage cost](/guides/manage-cost/manage-cost).
</Update>

<Update label="2025-10-16">
  ### Agentic quickstart

  Added new [agentic quickstart](/guides/get-started/quickstart#cursor) options to help you build Pinecone applications with AI coding agents like Claude Code and Cursor. Instead of copying code snippets, you work with an agent that understands Pinecone APIs and implements production-ready patterns automatically.
</Update>

<Update label="2025-10-16">
  ### AI Engine integration

  Added the [AI Engine](/integrations/ai-engine) integration page.
</Update>

<Update label="2025-10-09">
  ### Pinecone CLI v0.1.0

  We've released [v0.1.0](https://github.com/pinecone-io/cli/releases/tag/v0.1.0) of the [Pinecone CLI](https://github.com/pinecone-io/cli). The CLI lets you manage Pinecone infrastructure (organizations, projects, indexes, and API keys) directly from your terminal and in CI/CD.

  This feature is in [public preview](/release-notes/feature-availability). We'll be adding more features to the CLI over time, and we'd love your [feedback](https://community.pinecone.io/) on this early version.

  For more information, see the [CLI quickstart](/reference/cli/quickstart).
</Update>

## September 2025

<Update label="2025-09-30">
  ### Production best practices

  Added a new [error handling guide](/guides/production/error-handling) to help you handle errors gracefully in production, including implementing retry logic with exponential backoff for rate limits and transient errors.

  Updated the [production checklist](/guides/production/production-checklist) with enhanced guidance on data modeling, database limits, and performance optimization.
</Update>

<Update label="2025-09-11">
  ### Changing payment methods

  Added a new guide to help customers [change their payment method](/guides/organizations/manage-billing/change-payment-method) for Pinecone's Standard or Enterprise plan, including switching from credit card to marketplace billing and vice versa.
</Update>

<Update label="2025-09-04">
  ### Released Pinecone Terraform Provider v2.0.0

  Released [v2.0.0](https://github.com/pinecone-io/terraform-provider-pinecone/releases/tag/v2.0.0) of the [Terraform Provider for Pinecone](/integrations/terraform). This version adds support for managing API keys and projects.
</Update>

<Update label="2025-09-02">
  ### Multimodal context for assistants

  Assistants can now gather context from images in PDF files. To learn more, see [Multimodal context for assistants](/guides/assistant/multimodal). This feature is in [public preview](/release-notes/feature-availability).
</Update>

## August 2025

<Update label="2025-08-29">
  ### Filter lexical search by required terms

  You can now filter lexical search results to require specific terms. This is especially useful for filtering out results that don't contain essential keywords, requiring domain-specific terminology in results, and ensuring specific people, places, or things are mentioned. This feature is in [public preview](/release-notes/feature-availability).

  To learn more, see [Filter by required terms](/guides/search/lexical-search#filter-by-required-terms).
</Update>

<Update label="2025-08-26">
  ### Zapier integration

  Added the [Zapier](/integrations/zapier) integration page.
</Update>

<Update label="2025-08-25">
  ### SSO setup improvements

  We've streamlined the SSO setup process, eliminating the need to add placeholder URLs to your identity provider. To learn more, see [Configure SSO with Okta](/guides/production/configure-single-sign-on/okta).
</Update>

<Update label="2025-08-25">
  ### Update metadata across multiple records

  You can now [update metadata across multiple records](/guides/manage-data/update-data#update-metadata-across-multiple-records) in a namespace. This feature is in [early access](/release-notes/feature-availability).
</Update>

<Update label="2025-08-13">
  ### Data import from Azure Blob Storage

  Now, you can import data from an Azure Blob Storage container into a Pinecone index. This feature is in [public preview](/release-notes/feature-availability).

  To learn more, read:

  * [Integrate with Azure Blob Storage](/guides/operations/integrations/integrate-with-azure-blob-storage)
  * [Import records](/guides/index-data/import-data)
  * [Pinecone's pricing](https://www.pinecone.io/pricing/)
</Update>

<Update label="2025-08-12">
  ### Assistant MCP server endpoint update

  **Breaking Change**: After August 31, 2025 at 11:59:59 PM UTC, the SSE-based MCP endpoint for assistants (`/mcp/assistants/<YOUR_ASSISTANT_NAME>/sse`) will no longer work.

  Before then, update your applications to use the streamable HTTP transport MCP endpoint (`/mcp/assistants/<YOUR_ASSISTANT_NAME>`). This endpoint follows the current [MCP protocol specification](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http) and provides improved flexibility and compatibility.

  Please note that Assistant MCP servers are in [early access](/release-notes/feature-availability) and are not intended for production usage.

  For more information, see [Use an Assistant MCP server](/guides/assistant/mcp-server).
</Update>

<Update label="2025-08-04">
  ### VoltAgent integration

  Added the [VoltAgent](/integrations/voltagent) integration page.
</Update>

## July 2025

<Update label="2025-07-28">
  ### Increased context window for `pinecone-sparse-english-v0`

  You can now raise the context window for Pinecone's hosted [`pinecone-sparse-english-v0`](/guides/index-data/create-an-index#pinecone-sparse-english-v0) embedding model from `512` to `2048` using the `max_tokens_per_sequence` parameter.
</Update>

<Update label="2025-07-23">
  ### Release Go SDK v4.1.0, v4.1.1, and v4.1.2

  Released [`v4.1.0`](https://github.com/pinecone-io/go-pinecone/releases/tag/v4.1.0), [`v4.1.1`](https://github.com/pinecone-io/go-pinecone/releases/tag/v4.1.1), and [`v4.1.2`](https://github.com/pinecone-io/go-pinecone/releases/tag/v4.1.2) of the [Pinecone Go SDK](/reference/sdks/go/overview).

  * `v4.1.0` adds support for admin API operations for working with API keys, projects, and service accounts.
  * `v4.1.1` adds `PercentComplete` and `RecordsImported` to the response when [describing an import](/guides/index-data/import-data#track-import-progress) and [listing imports](/guides/index-data/import-data#list-imports).
  * `v4.1.2` adds support for [migrating a pod-based index to serverless](/guides/indexes/pods/migrate-a-pod-based-index-to-serverless#3-start-migration).
</Update>

<Update label="2025-07-23">
  ### Release Node.js SDK v6.1.2

  Released [`v6.1.2`](https://github.com/pinecone-io/pinecone-ts-client/releases/tag/v6.1.2) of the [Pinecone Node.js SDK](/reference/sdks/node/overview). This version adds support for the following:

  * [Migrating a pod-based index to serverless](/guides/indexes/pods/migrate-a-pod-based-index-to-serverless#3-start-migration).
  * Controlling whether `signed_url` is included in the response when [describing a file](/guides/assistant/manage-files#get-the-status-of-a-file) for an assistant.
</Update>

## June 2025

<Update label="2025-06-26">
  ### Unlimited assistant file storage for paid plans

  Organizations on the [Standard and Enterprise plans](https://www.pinecone.io/pricing/) now have [unlimited file storage](/reference/api/assistant/assistant-limits) for their assistants. Previously, organizations on these plans were limited to 10 GB of file storage per project.
</Update>

<Update label="2025-06-23">
  ### Data import from Google Cloud Storage

  You can now [import data](/guides/index-data/import-data) into an index from [Google Cloud Storage](/guides/operations/integrations/integrate-with-google-cloud-storage). This feature is in [public preview](/release-notes/feature-availability).
</Update>

<Update label="2025-06-20">
  ### Released Python SDK v7.1.0, v7.2.0, and v7.3.0

  Released [`v7.1.0`](https://github.com/pinecone-io/pinecone-python-client/releases/tag/v7.1.0), [`v7.2.0`](https://github.com/pinecone-io/pinecone-python-client/releases/tag/v7.2.0), and [`v7.3.0`](https://github.com/pinecone-io/pinecone-python-client/releases/tag/v7.3.0) of the [Pinecone Python SDK](/reference/sdks/python/overview).

  * `v7.1.0` fixes minor bugs.
  * `v7.2.0` adds support for [managing namespaces](/guides/manage-data/manage-namespaces).
  * `v7.3.0` adds support for admin API operations for working with API keys, projects, and service accounts.
</Update>

<Update label="2025-06-16">
  ### Released Go SDK v4.0.0 and v4.0.1

  Released [`v4.0.0`](https://github.com/pinecone-io/go-pinecone/releases/tag/v4.0.0) and [`v4.0.1`](https://github.com/pinecone-io/go-pinecone/releases/tag/v4.0.1) of the [Pinecone Go SDK](/reference/sdks/go/overview).

  Go SDK `v4.0.0` uses the latest stable API version, `2025-04`, and includes support for the following:

  * [Managing namespaces](/guides/manage-data/manage-namespaces)
  * [Reusing an index connection with a new namespace](/guides/manage-data/target-an-index#target-by-index-host-recommended) (see the Go example)
  * [Creating and managing backups](/guides/manage-data/back-up-an-index)
  * [Restoring indexes from backups](/guides/manage-data/restore-an-index)
  * [Listing embedding and reranking models hosted by Pinecone](/reference/api/2025-04/inference/list_models)
  * [Getting details about a model hosted by Pinecone](/reference/api/2025-04/inference/describe_model)

  Go SDK `v4.0.1` expands the [`DescribeIndex`](/guides/production/configure-private-endpoints#read-and-write-data) response to include the `private_host` value for connecting to indexes with a private endpoint.
</Update>

<Update label="2025-06-16">
  ### Released Node.js SDK v6.1.1

  Released [`v6.1.1`](https://github.com/pinecone-io/pinecone-ts-client/releases/tag/v6.1.1) of the [Pinecone Node.js SDK](/reference/sdks/node/overview). This version adds support for [setting the sampling temperature](/guides/assistant/chat-with-assistant#set-the-sampling-temperature) for an assistant, and expands the [`describeIndex`](/guides/production/configure-private-endpoints#read-and-write-data) response to include the `private_host` value for connecting to indexes with a private endpoint.
</Update>

<Update label="2025-06-12">
  ### Data modeling guide

  Added a new guide to help you [model your data](/guides/index-data/data-modeling) for efficient ingestion, retrieval, and management in Pinecone.
</Update>

<Update label="2025-06-05">
  ### Released Java SDK v5.1.0

  Released [`v5.1.0`](https://github.com/pinecone-io/pinecone-java-client/releases/tag/v5.1.0) of the [Pinecone Java SDK](/reference/sdks/java/overview). This version adds support for [listing](/reference/api/2025-04/inference/list_models) and [describing](/reference/api/2025-04/inference/describe_model) embedding and reranking models hosted by Pinecone.
</Update>

<Update label="2025-06-05">
  ### Released Node.js SDK v6.1.0

  Released [`v6.1.0`](https://github.com/pinecone-io/pinecone-ts-client/releases/tag/v6.1.0) of the [Pinecone Node.js SDK](/reference/sdks/node/overview). This version adds support for [controlling the context snippets sent to the LLM](/guides/assistant/chat-with-assistant#control-the-context-snippets-sent-to-the-llm) by an assistant.
</Update>

## May 2025

<Update label="2025-05-29">
  ### Released Python SDK v7.0.1 and v7.0.2

  Released [`v7.0.1`](https://github.com/pinecone-io/pinecone-python-client/releases/tag/v7.0.1) and [`v7.0.2`](https://github.com/pinecone-io/pinecone-python-client/releases/tag/v7.0.2) of the [Pinecone Python SDK](/reference/sdks/python/overview). These versions fix minor bugs discovered since the release of the `v7.0.0` major version.
</Update>

<Update label="2025-05-29">
  ### Released Node.s SDK v6.0.1

  Released [`v6.0.1`](https://github.com/pinecone-io/pinecone-ts-client/releases/tag/v6.0.1) of the [Pinecone Node.js SDK](/reference/sdks/node/overview). This version adds pagination to the [`listBackups`](/guides/manage-data/back-up-an-index#list-backups-in-a-project) operation.
</Update>

<Update label="2025-05-19">
  ### Pinecone API version `2025-04` is now the latest stable version

  `2025-04` is now the latest [stable version](/reference/api/versioning#release-schedule) of the [Pinecone APIs](/reference/api/introduction). For highlights, see the SDK releases below.
</Update>

<Update label="2025-05-19">
  ### Released Python SDK v7.0.0

  Released [`v7.0.0`](https://github.com/pinecone-io/pinecone-python-client/releases/tag/v7.0.0) of the [Pinecone Python SDK](/reference/sdks/python/overview). This version uses the latest stable API version, `2025-04`, and includes support for the following:

  * [Creating and managing backups](/guides/manage-data/back-up-an-index)
  * [Restoring indexes from backups](/guides/manage-data/restore-an-index)
  * [Listing embedding and reranking models hosted by Pinecone](/reference/api/2025-04/inference/list_models)
  * [Getting details about a model hosted by Pinecone](/reference/api/2025-04/inference/describe_model)
  * [Creating a BYOC index](/guides/production/bring-your-own-cloud#create-an-index)

  Additionally, the `pinecone-plugin-assistant` package required to work with [Pinecone Assistant](/guides/assistant/overview) is now included by default; it is no longer necessary to install the plugin separately.
</Update>

<Update label="2025-05-19">
  ### Released Node.js SDK v6.0.0

  Released [`v6.0.0`](https://github.com/pinecone-io/pinecone-ts-client/releases/tag/v6.0.0) of the [Pinecone Node.js SDK](/reference/sdks/node/overview). This version uses the latest stable API version, `2025-04`, and includes support for the following:

  * [Managing namespaces](/guides/manage-data/manage-namespaces)
  * [Creating and managing backups](/guides/manage-data/back-up-an-index)
  * [Restoring indexes from backups](/guides/manage-data/restore-an-index)
  * [Listing embedding and reranking models hosted by Pinecone](/reference/api/2025-04/inference/list_models)
  * [Getting details about a model hosted by Pinecone](/reference/api/2025-04/inference/describe_model)
</Update>

<Update label="2025-05-19">
  ### Released Java SDK v5.0.0

  Released [`v5.0.0`](https://github.com/pinecone-io/pinecone-java-client/releases/tag/v5.0.0) of the [Pinecone Java SDK](/reference/sdks/java/overview). This version uses the latest stable API version, `2025-04`, and includes support for the following:

  * [Creating indexes with integrated embedding and reranking](/guides/index-data/indexing-overview#integrated-embedding)
  * [Upserting text to an integrated index](/guides/index-data/upsert-data)
  * [Searching an integrated index with text](/guides/search/semantic-search#search-with-text)
  * [Managing namespaces](/guides/manage-data/manage-namespaces)
  * [Creating and managing backups](/guides/manage-data/back-up-an-index)
  * [Restoring indexes from backups](/guides/manage-data/restore-an-index)
</Update>

<Update label="2025-05-19">
  ### Released .NET SDK v4.0.0

  Released [`v4.0.0`](https://github.com/pinecone-io/pinecone-dotnet-client/releases/tag/4.0.0) of the [Pinecone .NET SDK](https://github.com/pinecone-io/pinecone-dotnet-client). This version uses the latest stable API version, `2025-04`, and includes support for the following:

  * [Creating indexes with integrated embedding and reranking](/guides/index-data/indexing-overview#integrated-embedding)
  * [Upserting text to an integrated index](/guides/index-data/upsert-data)
  * [Searching an integrated index with text](/guides/search/semantic-search#search-with-text)
  * [Managing namespaces](/guides/manage-data/manage-namespaces)
  * [Creating and managing backups](/guides/manage-data/back-up-an-index)
  * [Restoring indexes from backups](/guides/manage-data/restore-an-index)
  * [Listing embedding and reranking models hosted by Pinecone](/reference/api/2025-04/inference/list_models)
  * [Getting details about a model hosted by Pinecone](/reference/api/2025-04/inference/describe_model)

  <Warning>
    Before upgrading to `v4.0.0`, update all relevant code to account for the following [breaking changes](/reference/api/versioning#breaking-changes). See the [`v4.0.0`](https://github.com/pinecone-io/pinecone-dotnet-client/releases/tag/4.0.0) release notes for full details.

    * The [`create_index`](/reference/api/2025-04/control-plane/create_index) and [`create_for_model`](/reference/api/2025-04/control-plane/create_for_model) operations:
      * `CreateIndexRequestMetric` has been renamed to `MetricType`.
    * The [`list_indexes`](/reference/api/2025-04/control-plane/list_indexes) operation:
      * `ModelIndexEmbedMetric` has been renamed to `MetricType`.
    * The [`embed`](/reference/api/2025-04/inference/generate-embeddings) operation:
      * `SparseEmbedding.SparseIndices` has changed from `IEnumerable<int>` to `IEnumerable<long>`.
  </Warning>
</Update>

<Update label="2025-05-06">
  ### New Docs IA

  We've overhauled the information architecture of our guides to mirror the goals of users, from indexing to searching to optimizing to production.

  This change includes distinct pages for search types:

  * [Semantic search](https://docs.pinecone.io/guides/search/semantic-search)
  * [Lexical search](https://docs.pinecone.io/guides/search/lexical-search)
  * [Hybrid search](https://docs.pinecone.io/guides/search/hybrid-search)

  And optimization techniques:

  * [Increase relevance](https://docs.pinecone.io/guides/optimize/increase-relevance)
  * [Increase throughput](https://docs.pinecone.io/guides/optimize/increase-throughput)
  * [Decrease latency](https://docs.pinecone.io/guides/optimize/decrease-latency)
</Update>

## April 2025

<Update label="2025-04-25">
  ### Bring Your Own Cloud (BYOC) in GCP

  The [Bring Your Own Cloud (BYOC)](/guides/production/bring-your-own-cloud) offering is now available in GCP. Organizations with high security and compliance requirements can use BYOC to deploy Pinecone Database in their own GCP account. This feature is in [public preview](/release-notes/feature-availability).
</Update>

<Update label="2025-04-21">
  ### Integrate AI agents with Pinecone MCP

  [Pinecone's open-source MCP server](/guides/operations/mcp-server) enables AI agents to interact directly with Pinecone's functionality and documentation via the standardized [Model Context Protocol (MCP)](https://modelcontextprotocol.io/l). Using the MCP server, agents can search Pinecone documentation, manage indexes, upsert data, and query indexes for relevant information.
</Update>

<Update label="2025-04-21">
  ### Add context to AI agents with Assistant MCP

  Every Pinecone Assistant now has a [dedicated MCP server](/guides/assistant/mcp-server) that gives AI agents direct access to the assistant's knowledge through the standardized [Model Context Protocol (MCP)](https://modelcontextprotocol.io/).
</Update>

<Update label="2025-04-21">
  ### Upload a file from an in-memory binary stream

  You can [upload a file to an assistant directly from an in-memory binary stream](/guides/assistant/upload-files#upload-from-a-binary-stream) using the Python SDK and the BytesIO class.
</Update>

<Update label="2025-04-21">
  ### Released Pinecone Terraform Provider v1.0.0

  Released [v1.0.0](https://github.com/pinecone-io/terraform-provider-pinecone/releases/tag/v1.0.0) of the [Terraform Provider for Pinecone](/integrations/terraform). This version adds support for [sparse indexes](/guides/index-data/indexing-overview#indexes-with-sparse-vectors), [indexes with integrated embedding and reranking](/guides/index-data/indexing-overview#integrated-embedding), [index tags](/guides/manage-data/manage-indexes#configure-index-tags), and [index deletion protection](/guides/manage-data/manage-indexes#configure-deletion-protection).
</Update>

<Update label="2025-04-13">
  ### Released .NET SDK v3.1.0

  Released [`v3.1.0`](https://github.com/pinecone-io/pinecone-dotnet-client/releases/tag/3.1.0) of the [Pinecone .NET SDK](https://github.com/pinecone-io/pinecone-dotnet-client). This version adds support for [indexes with integrated embedding and reranking](/guides/index-data/indexing-overview#integrated-embedding).
</Update>

<Update label="2025-04-04">
  ### LLM shortcuts for Pinecone docs

  You can now use the "Copy page" options at the top of every page of the Pinecone documentation to quickly ground LLMs with Pinecone-specific context.
</Update>

## March 2025

<Update label="2025-03-26">
  ### Control the context snippets the assistant sends to the LLM

  You can [control the context snippets sent to the LLM](/guides/assistant/chat-with-assistant#control-the-context-snippets-sent-to-the-llm) by setting `context_options` in the request.
</Update>

<Update label="2025-03-24">
  ### Released Go SDK v3.1.0

  Released [`v3.1.0`](https://github.com/pinecone-io/go-pinecone/releases/tag/v3.1.0) of the [Pinecone Go SDK](/reference/sdks/go/overview). This version adds support for [indexes with integrated embedding and reranking](/guides/index-data/indexing-overview#integrated-embedding).
</Update>

<Update label="2025-03-21">
  <img />

  ### Launch week: Dark mode

  Dark mode is now out for Pinecone's website, docs, and console. You can change your theme at the top right of each site.
</Update>

<Update label="2025-03-20">
  ### Launch week: Self-service audit logs

  You can now enable and [configure audit logs](/guides/production/configure-audit-logs) for your Pinecone organization. [Audit logs](/guides/production/security-overview#audit-logs) provide a detailed record of user, service account, and API actions that occur within Pinecone. This feature is in [public preview](/release-notes/feature-availability) and available only on [Enterprise plans](https://www.pinecone.io/pricing/).
</Update>

<Update label="2025-03-19">
  ### Launch week: Introducing the Admin API and service accounts

  You can now use [service accounts](/guides/organizations/understanding-organizations#service-accounts) to programmatically manage your Pinecone organization through the Admin API. Use the Admin API to [create](/guides/projects/create-a-project) and [manage projects](/guides/projects/manage-projects), as well as [create and manage API keys](/guides/projects/manage-api-keys). The Admin API and service accounts are in [public preview](/release-notes/feature-availability).
</Update>

<Update label="2025-03-18">
  ### Launch week: Back up an index through the API

  You can now [back up an index](/guides/manage-data/back-up-an-index) and [restore an index](/guides/manage-data/restore-an-index) through the Pinecone API. This feature is in [public preview](/release-notes/feature-availability).
</Update>

<Update label="2025-03-17">
  ### Launch week: Optimized database architecture

  Pinecone has optimized its [serverless database architecture](/guides/get-started/database-architecture) to meet the growing demand for large-scale agentic workloads and improved performance for search and recommendation workloads. New customers will use this architecture by default, and existing customers will gain access over the next month.
</Update>

<Update label="2025-03-13">
  ### Firebase Genkit integration

  Added the [Firebase Genkit](/integrations/genkit) integration page.
</Update>

<Update label="2025-03-10">
  ### Bring Your Own Cloud (BYOC) in public preview

  [Bring Your Own Cloud (BYOC)](/guides/production/bring-your-own-cloud) lets you deploy Pinecone Database in your private AWS account to ensure data sovereignty and compliance, with Pinecone handling provisioning, operations, and maintenance. This feature is in [public preview](/release-notes/feature-availability) on AWS.
</Update>

## February 2025

<Update label="2025-02-21">
  ### Docs site refresh

  We've refreshed the look and layout of the [Pinecone documentation](https://docs.pinecone.io) site. You can now use the dropdown at the top of the side navigation to view documentation for either [Pinecone Database](/guides/get-started/overview) or [Pinecone Assistant](/guides/assistant/overview).
</Update>

<Update label="2025-02-18">
  ### Limit the number of chunks retrieved

  You can now limit the number of chunks the reranker sends to the LLM. To do this, set the `top_k` parameter (default is 15) when [retrieving context snippets](/guides/assistant/retrieve-context-snippets).
</Update>

<Update label="2025-02-21">
  ### Assistant Quickstart colab notebook

  Added the [Assistant Quickstart colab notebook](https://colab.research.google.com/github/pinecone-io/examples/blob/master/docs/assistant-quickstart.ipynb). This notebook shows you how to set up and use [Pinecone Assistant](/guides/assistant/overview) in your browser.
</Update>

<Update label="2025-02-18">
  ### Released Node.js SDK v5.0.0

  Released [`v5.0.0`](https://github.com/pinecone-io/pinecone-ts-client/releases/tag/v5.0.0) of the [Pinecone Node.js SDK](/reference/sdks/node/overview). This version uses the latest stable API version, `2025-01`, and includes support for [Pinecone Assistant](/guides/assistant/overview) and [sparse-only indexes](/guides/index-data/indexing-overview#indexes-with-sparse-vectors).
</Update>

<Update label="2025-02-11">
  ### New integrations

  Added the [Box](/integrations/box) and [Cloudera AI](/integrations/cloudera) integration pages.
</Update>

<Update label="2025-02-10">
  ### Citation highlights in assistant responses

  You can now include [highlights](/guides/assistant/chat-with-assistant#include-citation-highlights-in-the-response) in an assistant's citations. Highlights are the specific parts of the document that the assistant used to generate the response.

  Citation highlights are available in the Pinecone console or API versions `2025-04` and later.
</Update>

<Update label="2025-02-07">
  ### Pinecone API version `2025-01` is now the latest stable version

  `2025-01` is now the latest [stable version](/reference/api/versioning#release-schedule) of the [Pinecone APIs](/reference/api/introduction).
</Update>

<Update label="2025-02-07">
  ### Released Python SDK v6.0.0

  Released [`v6.0.0`](https://github.com/pinecone-io/pinecone-python-client/releases/tag/v6.0.0) of the [Pinecone Python SDK](/reference/sdks/python/overview). This version uses the latest stable API version, `2025-01`, and includes support for the following:

  * [Index tags](/guides/manage-data/manage-indexes#configure-index-tags) to categorize and identify your indexes.
  * [Integrated inference](/reference/api/introduction#inference) without the need for extra plugins. If you were using the preview functionality of integrated inference, you must uninstall the `pinecone-plugin-records` package to use the `v6.0.0` release.
  * Enum objects to help with the discoverability of some configuration options, for example, `Metric`, `AwsRegion`, `GcpRegion`, `PodType`, `EmbedModel`, `RerankModel`. This is a backwards compatible change; you can still pass string values for affected fields.
  * New client variants, `PineconeAsyncio` and `IndexAsyncio`, which provide `async` methods for use with [asyncio](https://docs.python.org/3/library/asyncio.html). This makes it possible to use Pinecone with modern async web frameworks such as [FastAPI](https://fastapi.tiangolo.com/), [Quart](https://quart.palletsprojects.com/en/latest/), and [Sanic](https://sanic.dev/en/). Async support should significantly increase the efficiency of running many upserts in parallel.

  <Warning>
    Before upgrading to `v6.0.0`, update all relevant code to account for the following [breaking changes](/reference/api/versioning#breaking-changes). See the [`v6.0.0`](https://github.com/pinecone-io/pinecone-python-client/releases/tag/v6.0.0) release notes for full details.

    * Incorporated the `pinecone-plugin-records` and `pinecone-plugin-inference` plugins into the `pinecone` package. If you are using these plugins, you must unstall them to use `v6.0.0`.
    * Dropped support for Python 3.8, which has now reached official end of life, and added support for Python 3.13.
    * Removed the explicit dependency on `tqdm`, which is used to provide a progress bar when upserting data into Pinecone. If `tqdm` is available in the environment, the Pinecone SDK will detect and use it, but `tdqm` is no longer required to run the SDK. Popular notebook platforms such as [Jupyter](https://jupyter.org/) and [Google Colab](https://colab.google/) already include `tqdm` in the environment by default, but if you are running small scripts in other environments and want to continue seeing progress bars, you will need to separately install the `tqdm` package.
    * Removed some previously deprecated and rarely used keyword arguments (`config`, `openapi_config`, and `index_api`) to instead prefer dedicated keyword arguments for individual settings such as `api_key`, `proxy_url`, etc.
  </Warning>
</Update>

<Update label="2025-02-07">
  ### Released Java SDK v4.0.0

  Released [`v4.0.0`](https://github.com/pinecone-io/pinecone-java-client/releases/tag/v4.0.0) of the [Pinecone Java SDK](/reference/sdks/java/overview). This version uses the latest stable API version, `2025-01`, and adds support for [sparse-only indexes](/guides/index-data/indexing-overview#indexes-with-sparse-vectors).

  <Warning>
    Before upgrading to `v4.0.0`, update all relevant code to account for the following [breaking changes](/reference/api/versioning#breaking-changes). See the [`v4.0.0`](https://github.com/pinecone-io/pinecone-java-client/releases/tag/v4.0.0) release notes for full details.

    * [`embed` method](/reference/api/2025-01/inference/generate-embeddings):
      * `parameters` now accepts `Map<String, Object>` instead of `EmbedRequestParameters`.
      * The `Embeddings` response class now has dense and sparse embeddings. You now must use `getDenseEmbedding()` or `getSparseEmbedding()`. For example, instead of `embeddings.getData().get(0).getValues()`, you would use `embeddings.getData().get(0).getDenseEmbedding().getValues()`.

    * [`rerank` method](/guides/search/rerank-results):
      * `documents` now accepts `List<Map<String, Object>>` instead of `List<Map<String, String>>`.
      * `parameters` now accepts `Map<String, Object>` instead of `Map<String, String>`.
  </Warning>
</Update>

<Update label="2025-02-07">
  ### Released Go SDK v3.0.0

  Released [`v3.0.0`](https://github.com/pinecone-io/go-pinecone/releases/tag/v3.0.0) of the [Pinecone Go SDK](/reference/sdks/go/overview). This version uses the latest stable API version, `2025-01`, and adds support for [sparse-only indexes](/guides/index-data/indexing-overview#indexes-with-sparse-vectors).

  <Warning>
    Before upgrading to `v3.0.0`, update all relevant code to account for the following [breaking changes](/reference/api/versioning#breaking-changes). See the [`v3.0.0`](https://github.com/pinecone-io/go-pinecone/releases/tag/v3.0.0) release notes for full details.

    * [`embed` operation](/reference/api/2025-01/inference/generate-embeddings):
      * `EmbedParameters` is no longer typed as a pointer.
    * [`create_index` operation](/guides/index-data/create-an-index):
      * `CreateServerlessIndexRequest` and `CreatePodIndexRequest` structs have been updated, and fields are now classified as pointers to better denote optionality around creating specific types of indexes: `Metric`, `Dimension`, `VectorType`, and `DeletionProtection`.
    * Various data operation:
      * `Values` in the `Vector` type are now a pointer to allow flexibility when working with sparse-only indexes.
  </Warning>
</Update>

<Update label="2025-02-07">
  ### Released .NET SDK v3.0.0

  Released [`v3.0.0`](https://github.com/pinecone-io/pinecone-dotnet-client/releases/tag/3.0.0) of the [Pinecone .NET SDK](https://github.com/pinecone-io/pinecone-dotnet-client). This version uses the latest stable API version, `2025-01`, and adds support for [sparse-only indexes](/guides/index-data/indexing-overview#indexes-with-sparse-vectors).

  <Warning>
    Before upgrading to `v3.0.0`, update all relevant code to account for the following [breaking changes](/reference/api/versioning#breaking-changes). See the [`v3.0.0`](https://github.com/pinecone-io/pinecone-dotnet-client/releases/tag/3.0.0) release notes for full details.

    * [`embed` operation](/reference/api/2025-01/inference/generate-embeddings):
      * The `Embedding` type has changed from a simple object to a discriminated union, supporting both `DenseEmbedding` and `SparseEmbedding`. New helper methods available on the Embedding type: `IsDense` and `IsSparse` for type checking, `AsDense()` and `AsSparse()` for type conversion, and `Match()` and `Visit()` for pattern matching.
      * The `Parameters` property now uses `Dictionary<string, object?>?` instead of `EmbedRequestParameters`.

    * `rerank` operation:
      * The `Document` property now uses `Dictionary<string, object?>?` instead of `Dictionary<string, string>?`.
      * The `Parameters` property now uses `Dictionary<string, object?>?` instead of `Dictionary<string, string>?`.
  </Warning>
</Update>

## January 2025

<Update label="2025-01-29">
  ### Update to the API keys page

  Added the **Created by** column on the [API keys page](https://app.pinecone.io/organizations/-/projects/-/keys) in the Pinecone Console. This column shows the email of the user who created the API key.
</Update>

<Update label="2025-01-29">
  ### Sparse-only indexes in early access

  You can now use [sparse-only indexes](/guides/index-data/indexing-overview#indexes-with-sparse-vectors) for the storage and retrieval of sparse vectors. This feature is in [early access](/release-notes/feature-availability).
</Update>

<Update label="2025-01-22">
  <img />

  Pinecone Assistant is generally available (GA) for all users.

  [Read more](https://www.pinecone.io/blog/pinecone-assistant-generally-available) about the release on our blog.
</Update>

<Update label="2025-01-09">
  ### Released Node SDK v4.1.0

  Released [`v4.1.0`](https://github.com/pinecone-io/pinecone-ts-client/releases/tag/4.1.0) of the [Pinecone Node.js SDK](/reference/sdks/node/overview). This version adds support for [index tags](/guides/manage-data/manage-indexes#configure-index-tags) when creating or configuring indexes. It also adds a new `RetryOnServerFailure` class that automatically retries asynchronous operations with exponential backoff when the server responds with a `500` or `503` [error](/reference/api/errors).
</Update>

<Update label="2025-01-09">
  ### New Billing Admin user role

  Added the Billing Admin [user role](/guides/organizations/understanding-organizations#organization-roles). Billing Admins have permissions to view billing details, usage details, and support plans.
</Update>

<Update label="2025-01-07">
  ### Released Go SDK v2.2.0

  Released [`v2.2.0`](https://github.com/pinecone-io/go-pinecone/releases/tag/v2.2.0) of the [Pinecone Go SDK](/reference/sdks/go/overview). This version adds support for [index tags](/guides/manage-data/manage-indexes#configure-index-tags) when creating or configuring indexes.
</Update>


# 2026 releases
Source: https://docs.pinecone.io/assistant-release-notes/2026

Pinecone release notes for 2026: new features, improvements, and API changes.

## August 2026

<Update label="2026-08-11">
  ### New guide: reciprocal rank fusion (RRF)

  Added a guide on [reciprocal rank fusion](/guides/search/reciprocal-rank-fusion), a client-side method for combining the results of separate searches (for example, full-text and semantic) into one ranking without normalizing scores. RRF fuses rankings rather than raw scores, so it needs no per-signal weighting.
</Update>

<Update label="2026-08-01">
  ### Released Pinecone Terraform Provider v4.0.0

  Released [v4.0.0](https://github.com/pinecone-io/terraform-provider-pinecone/releases/tag/v4.0.0) of the [Terraform Provider for Pinecone](/integrations/terraform). This version adds resources for managing [service accounts](/guides/organizations/manage-service-accounts), [role bindings](/guides/production/manage-rbac), organization invites, and removing organization members. It also adds data sources for reading existing indexes, collections, projects, service accounts, role bindings, invites, and users, and `terraform import` support for every resource.
</Update>

## July 2026

<Update label="2026-07-21">
  ### Fuzzy matching and substring search for full-text search

  [Full-text search](/guides/search/full-text-search) now supports two new ways to match text:

  * **Fuzzy matching (typo tolerance)** — In a `query_string` search, append `~` to a term to match indexed terms within a small edit distance: `body:(compxter~1)` matches `computer`. Use `term~` for an automatic distance based on term length, or `term~N` for a fixed distance (`N` is 0–2). Fuzzy works on existing indexes with no reindex. See [Fuzzy matching](/guides/search/full-text-search#query-syntax-reference).
  * **Substring search with n-grams** — Configure a text field for character n-gram tokenization to match on partial words, prefixes, and autocomplete-style queries. Add an `ngram` object (`min_gram`, `max_gram`, `prefix_only`) to a field's `full_text_search` config at index creation, then query it with ordinary `text` or `query_string` searches. See [Substring search with n-grams](/guides/search/full-text-search#substring-search-with-n-grams).

  Full-text search remains in [public preview](/release-notes/feature-availability) under API version `2026-01.alpha`.
</Update>

<Update label="2026-07-20">
  ### Manage roles from your identity provider with SAML and SCIM

  Organizations on the Enterprise plan with SSO can now manage Pinecone roles directly from their identity provider (IdP), instead of assigning them manually in Pinecone. Two modes are available:

  * **SAML role management** sets each user's organization and project roles from a SAML attribute on every SSO login.
  * **SCIM provisioning** syncs members and their roles in real time as you add, update, deactivate, or remove them in your IdP.

  Both modes use the same `pinecone:*` role values and work with Okta and other SAML 2.0 / SCIM 2.0 providers. Configure them under **Settings > Access > Identity provider** in the Pinecone console. For more information, see [Manage roles with Okta](/guides/production/configure-single-sign-on/okta-role-management) and [SCIM provisioning with Okta](/guides/production/configure-single-sign-on/okta-scim-provisioning).
</Update>

<Update label="2026-07-13">
  ### Expanded role-based access controls (RBAC)

  Pinecone now offers an expanded set of roles for managing access to organizations and projects. New **Organization member** and **Project member** roles grant more restricted access than the owner and manager roles, and projects now support granular editor and viewer roles (project, control plane, and data plane) that you can assign to users, service accounts, and API keys.

  To better communicate the access hierarchy, organization owners are now shown in each project's member list. This replaces the separate project-role assignments that could fall out of sync with the access organization owners inherit to all projects. Effective permissions are unchanged.

  If you used the previous role model, the **User** role has been renamed to **Manager**: the organization-level **User** role is now **Organization manager**, and the project-level **User** role is now **Project manager**. This is a name change only—permissions are unchanged and existing assignments are migrated automatically.

  You can assign and manage roles in the [Pinecone console](https://app.pinecone.io) or programmatically with the Admin API. For more information, see [Manage roles and access](/guides/production/manage-rbac), [Organization roles](/guides/organizations/understanding-organizations#organization-roles), and [Project roles](/guides/projects/understanding-projects#project-roles).
</Update>

<Update label="2026-07-02">
  ### Public preview: Restore a backup to a different region

  You can now restore a [serverless backup](/guides/manage-data/backups-overview) into a different region on the same cloud provider. Use the `unstable` version of the create index endpoint, specifying the backup as `source_backup_id` within `spec.serverless` and the target region there. Restoring to a different cloud provider is not supported, and the feature is currently available through the REST API only.

  For details, see [Restore to a different region](/guides/manage-data/restore-an-index#restore-to-a-different-region).
</Update>

<Update label="2026-07-01">
  ### Cohere Rerank 4.0 Fast is generally available, and cohere-rerank-3.5 is deprecated

  [`cohere-rerank-4-fast`](/models/cohere-rerank-4-fast) (Cohere Rerank 4.0 Fast) is now generally available as a [reranking model](/guides/search/rerank-results#reranking-models) on Pinecone. It succeeds `cohere-rerank-3.5`, improves relevance quality, and supports multiple rerank fields. Cohere Rerank 4.0 is hosted on Azure AI under the Global Standard deployment type, and requests may be processed in regions outside the United States.

  With this release, [`cohere-rerank-3.5`](/models/cohere-rerank-3.5) is **deprecated**:

  * **Through July 31, 2026**: `cohere-rerank-3.5` continues to serve requests as before.
  * **August 1, 2026**: requests to `cohere-rerank-3.5` are automatically served by `cohere-rerank-4-fast`.

  No code change is required for the transition, but note two differences before you migrate:

  * **Relevance scores differ.** `cohere-rerank-4-fast` returns different scores than `cohere-rerank-3.5`. If your application relies on hard-coded score thresholds, re-tune them against `cohere-rerank-4-fast` before August 1.
  * **Billing counts units differently.** The per-unit rate is unchanged at \$2.00 per 1,000 rerank units. One rerank unit covers a query plus up to 100 documents, with documents longer than \~500 tokens auto-chunked into \~500-token chunks that each count toward that 100. As a result, `cohere-rerank-4-fast` can bill multiple units for a large request, whereas `cohere-rerank-3.5` billed one unit per request.

  To control the transition yourself, migrate your rerank requests to `cohere-rerank-4-fast` before August 1. For model details and parameters, see [Reranking models](/guides/search/rerank-results#reranking-models).
</Update>

## June 2026

<Update label="2026-06-03">
  ### Multi-region and multi-cloud support on the Builder plan

  The [Builder plan](https://www.pinecone.io/pricing/) now supports serverless indexes in every generally available cloud region, the same regions available on the Standard and Enterprise plans. Previously, Builder indexes were limited to the `us-east-1` region of AWS.

  Highlights:

  * **All supported regions** — Create Builder serverless indexes across AWS, GCP, and Azure, including `us-west-2` (Oregon), `eu-west-1` (Ireland), `eu-central-1` (Frankfurt), `ap-southeast-1` (Singapore), `us-central1` (Iowa), `europe-west4` (Netherlands), and `eastus2` (Virginia).
  * **Lower latency and data residency** — Deploy indexes closer to your application or in a region that meets your data residency requirements, without upgrading to Standard or Enterprise.
  * **No pricing change** — Builder remains a flat \$20/month plan with no usage overages.

  The Starter plan continues to support the `us-east-1` region of AWS only. For the full list of supported regions, see [Cloud regions](/guides/index-data/create-an-index#cloud-regions). For plan quotas, see [Database limits](/reference/api/database-limits).
</Update>

<Update label="2026-06-01">
  ### Cheaper bulk imports and free import credit

  [Importing from object storage](/guides/index-data/import-data) is now cheaper: the bulk-import overage rate is **\$0.25/GB**, down from \$1/GB.

  In addition, **Standard and Enterprise** organizations now get a **one-time \$250 bulk import credit** (1 TB), valid through July 31, 2026. Usage beyond the credit is billed at the new \$0.25/GB rate. Builder and Starter plans are not eligible.

  For details, see [Understanding cost — Imports](/guides/manage-cost/understanding-cost#imports).
</Update>

## May 2026

<Update label="2026-05-05">
  ### Public preview: Pinecone Marketplace

  [Pinecone Marketplace](/guides/marketplace/overview) is now in [public preview](/release-notes/feature-availability). Marketplace lets you build, publish, and operate AI-powered knowledge applications on top of Pinecone, with a managed deployment lifecycle and end-user chat interface.

  Highlights:

  * **Templates and connectors** — Start from pre-built templates, connect data sources (Google Drive, manual upload), and configure knowledge processing with the Knowledge Agent Toolkit (KAT).
  * **Multi-domain routing** — Route end-user queries across multiple knowledge domains within a single deployment.
  * **Evaluations and analytics** — Run evaluations against your deployment and monitor usage with event logs.
  * **Versioning and rollback** — Publish deployment versions and roll back to previous configurations.
  * **End-user experience** — Authenticated chat interface with citations, visual components, and feedback collection.
  * **Increased Starter plan limits** - The Starter plan is currently offering 1M input tokens per month (500K before promotion) to help explore Marketplace apps until June 30, 2026.

  For details, see the [Marketplace quickstart](/guides/marketplace/quickstart) and [Marketplace API reference](/reference/api/marketplace/introduction).
</Update>

<Update label="2026-05-04">
  ### New Builder plan

  The [Builder plan](https://www.pinecone.io/pricing/) is now available at **\$20/month** (flat). Builder is designed for individual developers who need higher limits than Starter without committing to usage-based pricing. Key differences from Starter:

  * **10 serverless indexes** (up from 5)
  * **10 GB storage per organization**
  * **100 namespaces per index** (up from 20)
  * **Prometheus and Datadog monitoring**

  Builder is a fixed-price plan with no overages. When you hit a quota, operations are blocked rather than billed. Payment is by credit or debit card only. You can upgrade from Starter or downgrade from Standard at any time in the Pinecone console.

  For full quotas, see [Database limits](/reference/api/database-limits). For billing details, see [Understanding cost](/guides/manage-cost/understanding-cost).
</Update>

<Update label="2026-05-04">
  ### Public preview: Full-text search

  [Full-text search](/guides/search/full-text-search) is now in [public preview](/release-notes/feature-availability). Full-text search uses a typed document model: you upsert data as JSON documents, declare ranking fields in a schema, and Pinecone indexes them accordingly. Schema field types: `string` with `full_text_search` (indexed for BM25 ranking), `dense_vector`, and `sparse_vector`. Any other fields you upsert are stored as metadata and automatically indexed for filtering — no schema declaration required.

  Highlights:

  * **Four scoring methods** via `score_by`: `text` (BM25), `query_string` (Lucene syntax, including cross-field boolean queries), `dense_vector`, and `sparse_vector`.
  * **New data plane endpoints** under `/namespaces/{namespace}/documents/`: `upsert`, `search`, `fetch`, and `delete`.
  * **New filter operator** `$match_phrase` for phrase matching against text fields, composable with any `score_by` method.
  * **Flexible deployment**: on-demand read capacity (`read_capacity.mode: "OnDemand"`) and dedicated read capacity (`read_capacity.mode: "Dedicated"`) are both supported on managed (serverless) indexes.

  Use API version `2026-01.alpha` to access the feature.
</Update>

<Update label="2026-05-01">
  ### New AWS regions for serverless indexes

  You can now deploy [serverless indexes](/guides/index-data/indexing-overview) in two new AWS regions: `eu-central-1` (Frankfurt) and `ap-southeast-1` (Singapore). Both regions are available on Standard and Enterprise plans. For the full list of supported regions, see [Cloud regions](/guides/index-data/create-an-index#cloud-regions).
</Update>

## April 2026

<Update label="2026-04-28">
  ### General availability: Fetch by metadata

  The [Fetch by metadata](/reference/api/latest/data-plane/fetch_by_metadata) operation is now [generally available](/release-notes/feature-availability) and recommended for production usage. Use a metadata filter expression to fetch matching records without knowing their IDs, and paginate with `paginationToken` to retrieve result sets larger than 10,000 records per response.

  For more information, see [Fetch records by metadata](/guides/manage-data/fetch-data#fetch-records-by-metadata).
</Update>

<Update label="2026-04-21">
  ### Upsert files with custom IDs in Assistant

  Pinecone Assistant now supports [upserting files](/guides/assistant/upload-files#upsert-a-file) with user-provided file IDs, so you can create or replace a file by a stable custom identifier instead of relying on system-generated UUIDs. For more information, see [File identifiers](/guides/assistant/files-overview#file-identifiers).

  As part of this update, [upload](/guides/assistant/upload-files), upsert, and delete operations now return an operation object that can be polled for status and progress. Assistant also includes new API endpoints to [list and describe file operations](/guides/assistant/manage-files#track-file-operations).

  This update applies to the API only; SDK support is not yet available.
</Update>

<Update label="2026-04-15">
  ### General availability: Dedicated Read Nodes

  [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are now [generally available](/release-notes/feature-availability) and recommended for production usage on Standard and Enterprise plans. You can provision read hardware for large, high-throughput indexes that need predictable, low latency using the console and API.
</Update>

<Update label="2026-04-01">
  ### Pinecone Assistant usage-based pricing and monthly Starter limits

  Pinecone Assistant pricing is now fully usage-based. The hourly per-assistant fee has been removed. On Standard and Enterprise, you pay for what you use: ingestion (file uploads and updates on an assistant), storage, and chat, context, and evaluation tokens — with no base charge per assistant.

  For the Starter plan, Assistant included allowances are now monthly and reset each billing period (they are no longer all-time project totals). Starter includes **500,000 chat input tokens, 300,000 chat output tokens, 500,000 context retrieval tokens, and 1,000 ingestion units** per month. When you upload files to an assistant, usage is measured in ingestion units (approximately one unit per chunk, \~400 tokens); multimodal PDF chunks account for more ingestion units per chunk than standard text on the same meter.

  Per-assistant file count limits have been removed for all plans. Usage is governed by ingestion and storage allowances, file size and page limits, and rate limits instead of a cap on the number of stored documents.

  For details, see [Pricing and limits](/guides/assistant/pricing-and-limits) and [Pinecone pricing](https://www.pinecone.io/pricing/).
</Update>

## March 2026

<Update label="2026-03-26">
  ### General availability: platform and operations features

  The following capabilities are now [generally available](/release-notes/feature-availability) and recommended for production usage:

  * **Namespace creation** — [Create namespace API](/guides/manage-data/manage-namespaces)
  * **Pinecone MCP server** — [Integrate AI agents with Pinecone](/guides/operations/mcp-server)
  * **Assistant MCP server** — [Use an Assistant MCP server](/guides/assistant/mcp-server)
  * **Bulk metadata updates** — [Update metadata across multiple records](/guides/manage-data/update-data#update-metadata-across-multiple-records)
  * **Customer-managed encryption keys (CMEK)** — [Configure CMEK](/guides/production/configure-cmek)
  * **Data import from object storage** (Amazon S3, Google Cloud Storage, Azure Blob Storage) — [Import records](/guides/index-data/import-data)
  * **Audit logs** — [Configure audit logs](/guides/production/configure-audit-logs)
  * **Admin API and service accounts** (organization- and project-level) — [Manage service accounts](/guides/organizations/manage-service-accounts), [Manage service accounts at the project level](/guides/projects/manage-service-accounts)
  * **Backups and restore** (serverless indexes) — [Back up an index](/guides/manage-data/back-up-an-index), [Restore an index](/guides/manage-data/restore-an-index)
  * **Pinecone Local** (local development emulator) — [Local development](/guides/operations/local-development)
  * **Automated testing with Pinecone Local** — [Automated testing](/guides/production/automated-testing)
  * **Indexes with sparse vectors** — [Indexes with sparse vectors](/guides/index-data/indexing-overview#indexes-with-sparse-vectors)
  * **`pinecone-sparse-english-v0`** — [Sparse English embedding model](/guides/search/rerank-results#pinecone-sparse-english-v0)
  * **Prometheus monitoring** (serverless indexes) — [Monitor with Prometheus](/guides/production/monitoring#monitor-with-prometheus)
  * **Evaluate answers (`metrics_alignment`)** — [Evaluate answers](/guides/assistant/evaluate-answers)
  * **Manage storage integrations** — [Manage storage integrations](/guides/operations/integrations/manage-storage-integrations)
</Update>

<Update label="2026-03-03">
  ### Released Pinecone Terraform Provider v3.0.0

  Released [v3.0.0](https://github.com/pinecone-io/terraform-provider-pinecone/releases/tag/v3.0.0) of the [Terraform Provider for Pinecone](/integrations/terraform). This version adds support for [BYOC indexes](/guides/production/bring-your-own-cloud), [dedicated read nodes](/guides/index-data/dedicated-read-nodes), and [metadata indexing](/guides/index-data/create-an-index#metadata-indexing) on serverless and BYOC indexes.
</Update>

## February 2026

<Update label="2026-02-19">
  ### BYOC now available on AWS, GCP, and Azure

  [Bring Your Own Cloud (BYOC)](/guides/production/bring-your-own-cloud) is now available in [public preview](/release-notes/feature-availability) on AWS, GCP, and Azure. BYOC lets you run Pinecone's data plane inside your own cloud account with a zero-access operating model — Pinecone never needs SSH, VPN, or inbound network access to your infrastructure.

  Deploy using a self-serve Pulumi-based setup wizard, with pull-based operations that execute locally in your cluster. Your vectors, metadata, and queries never leave your environment.
</Update>

<Update label="2026-02-01">
  ### HIPAA compliance add-on for Standard plan

  HIPAA compliance is now available as an optional add-on for [Standard plan](https://www.pinecone.io/pricing/) customers. For **\$190 per month**, you get HIPAA-ready infrastructure, encrypted data storage, audit logging, enhanced security controls, and BAA execution and compliance documentation support.

  Full HIPAA compliance remains included with the Enterprise plan. To enable the add-on on the Standard plan, [contact sales](mailto:sales@pinecone.io) or see [Understanding cost — HIPAA compliance add-on](/guides/manage-cost/understanding-cost#hipaa-compliance-add-on).
</Update>

## January 2026

<Update label="2026-01-28">
  ### Claude model deprecation for Assistant

  Anthropic has [deprecated](https://platform.claude.com/docs/en/about-claude/model-deprecations) the Claude 3.5 Sonnet and Claude 3.7 Sonnet models. Pinecone Assistant automatically routes all chat requests that specify `claude-3-5-sonnet` or `claude-3-7-sonnet` to Claude Sonnet 4.5, which provides enhanced intelligence at the same price. No code changes are required.

  To update your code to explicitly use Claude Sonnet 4.5, set `model: "claude-sonnet-4-5"` in your chat requests. For more information, see [Choose a model](/guides/assistant/chat-with-assistant#choose-a-model).
</Update>

<Update label="2026-01-28">
  ### Pinecone Assistant node for n8n

  The official Pinecone Assistant n8n node brings Assistant's end-to-end RAG capabilities directly into n8n workflows, letting you connect any data source to AI-backed automation.

  For more information, see the [Assistant quickstart for n8n](/guides/assistant/quickstart/n8n-quickstart).
</Update>

<Update label="2026-01-27">
  ### Claude Sonnet 4.5 now available for Assistant chat

  Pinecone Assistant now supports Anthropic's Claude Sonnet 4.5 model. To use this model, set `model: "claude-sonnet-4-5"` in your [chat](/reference/api/latest/assistant/chat_assistant) requests. In the Pinecone console, Claude Sonnet 4.5 is also available as a selection in the **Chat model** dropdown menu in the playground for each assistant.

  For more information, see [Choose a model](/guides/assistant/chat-with-assistant#choose-a-model).
</Update>

<Update label="2026-01-23">
  ### Metadata filter limit: 10,000 values per `$in`/`$nin` operator

  Pinecone now enforces a limit of 10,000 values per `$in` or `$nin` operator in metadata filter expressions. This limit helps ensure consistent query performance and protects shared infrastructure from excessive load caused by very large filters.

  Requests that exceed this limit will fail with a `400 - BAD_REQUEST` error.

  If your application currently uses large `$in` filters (especially for access control), consider these approaches:

  * **Namespace-based isolation** (recommended): Create separate namespaces for each tenant instead of filtering by thousands of tenant IDs. This can also reduce query costs (queries on a 1 GB namespace cost 1 RU instead of 100 RUs for a 100 GB namespace with filtering).
  * **Access control groups**: Filter by organization, project, or role identifiers instead of individual user IDs.
  * **Post-filter client-side**: Retrieve a larger top K without filtering, then filter results in your application.

  For more information, see [Metadata filter limits](/reference/api/database-limits#metadata-filter-limits) and [Design for multi-tenancy](/guides/index-data/data-modeling#design-for-multi-tenancy).
</Update>

<Update label="2026-01-16">
  ### Request-per-second limits for data plane operations

  Pinecone now enforces request-per-second rate limits on data plane operations (query, upsert, delete, and update) at the namespace level. These limits are set to 100 requests per second per namespace for all plans and provide protection against excessive request rates.

  Request-per-second limits are enforced in addition to existing read unit and write unit limits. If you exceed a request-per-second limit, you'll receive a `429 - TOO_MANY_REQUESTS` error.

  For more information, see [Database limits](/reference/api/database-limits#data-plane-operations-requests-per-second-limits).
</Update>

<Update label="2026-01-15">
  ### Pagination support for fetch by metadata

  The [Fetch by metadata](/reference/api/latest/data-plane/fetch_by_metadata) operation now supports pagination, allowing you to fetch large result sets in multiple requests. Use the `paginationToken` parameter to retrieve the next page of results.

  When there are more results available, the response includes a `pagination` object with a `next` token. Pass this token as the `paginationToken` parameter in subsequent requests to fetch the next page. When there are no more results, the response does not include a `pagination` object.

  For more information, see [Fetch records by metadata](/guides/manage-data/fetch-data#fetch-records-by-metadata).
</Update>


# Feature availability
Source: https://docs.pinecone.io/assistant-release-notes/feature-availability

Pinecone feature availability across public preview, general availability, and limited availability releases, with links to release notes.

This page defines the different availability phases of a feature in Pinecone.

The availability phases are used to communicate the maturity and stability of a feature. The availability phases are:

* **Early access**: In active development and may change at any time. Intended for user feedback only. In some cases, users must be granted explicit access to the API by Pinecone.

* **Public preview**: Unlikely to change between public preview and general availability. Not recommended for production usage. Available to all users.

* **Limited availability**: Available to select customers in a subset of regions and providers for production usage.

* **General availability**: Will not change on short notice. Recommended for production usage. Officially [supported by Pinecone](/troubleshooting/pinecone-support-slas) for non-production and production usage.

* **Deprecated**: Still supported, but no longer under active development, except for critical security fixes. Existing usage will continue to function, but migration following the upgrade guide is strongly recommended. Will be removed in the future at an announced date.

* **End of life (EOL)**: Removed, and no longer supported or available.

<Note>
  A feature is in **general availability** unless explicitly marked otherwise.
</Note>


# Assistant examples
Source: https://docs.pinecone.io/examples/assistant

Notebooks and Next.js sample apps for Pinecone Assistant: quickstart, context snippet retrieval, and a full-stack chat UI with citations.

<div>
  <ExampleCard title="Quickstart">
    <Tag />
  </ExampleCard>

  <ExampleCard title="Retrieve context snippets">
    <Tag />
  </ExampleCard>

  <ExampleCard title="Pinecone Assistant">
    <Tag icon="/images/examples/nextjs.svg" />
  </ExampleCard>
</div>


# Marketplace concepts
Source: https://docs.pinecone.io/guides/marketplace/concepts

Learn Pinecone Marketplace concepts including knowledge applications, deployments, templates, manifests, KAT routing, layouts, and visual components.

<Note>
  This feature is in [public preview](/release-notes/feature-availability).
</Note>

This page defines the core concepts in Pinecone Marketplace. For a hands-on introduction, see the [Quickstart](/guides/marketplace/quickstart).

## Knowledge application

A **knowledge application** is the consumer-facing product an operator publishes. It has a branded interface, one or more knowledge domains, and a defined access policy. End users interact with a knowledge application; they do not interact directly with the underlying Pinecone assistants.

## Deployment

A **deployment** is the unit an operator owns and manages. It contains the configuration, connected sources, versions, and access settings for a single knowledge application. Each deployment has its own dashboard, analytics, and event log.

## Template

A **template** is a vertical configuration that bundles operating parameters, suggested layout, recommended sources, and starter prompts for a specific use case. Marketplace ships with a catalog of templates (presented as **Apps** in the catalog UI), such as Customer Support, HR Benefits, Legal Document Search, and Sales Enablement. See [Template catalog](/guides/marketplace/template-catalog).

A template provides a starting point. Operators customize it through the setup wizard, then can keep iterating after the deployment is published.

## Version

A **version** is a snapshot of a deployment that you can publish, evaluate, and roll back to. When an operator edits an active deployment, Marketplace creates a new building version. Publishing promotes that version to active and triggers background provisioning, introspection, starter generation, and evaluation. Previous versions remain available for rollback.

See [Manage versions and rollback](/guides/marketplace/manage-versions-and-rollback).

## Knowledge base

A **knowledge base** is a single knowledge domain inside a deployment, backed by a Pinecone assistant. A deployment can have one or many knowledge bases. Multi-knowledge-base deployments use [KAT](#kat) to route between domains.

## Manifest

A **manifest** is an automatically generated description of what a knowledge base can answer, what is in scope, and what is out of scope. Marketplace builds manifests through progressive introspection: after publish, it probes each assistant with sampled questions and uses the responses to construct the manifest. KAT uses manifests at query time to route, disambiguate, and refuse out-of-scope questions.

See [Manifests](/guides/marketplace/kat-overview#manifests).

## KAT

**KAT** (Knowledge Agent Toolkit) is the orchestration layer that turns one or more knowledge bases into a coherent multi-domain application. KAT handles intent extraction, slot filling, multi-domain routing, disambiguation, and guardrails.

KAT supports two execution modes:

* `full`: runs the complete pipeline, including answer synthesis.
* `disambiguation_only`: routes and disambiguates, then delegates synthesis to Pinecone Assistant.

For single-knowledge-base deployments, you can use simpler strategies: `single`, `fan_out`, or `llm_classify`.

See [KAT overview](/guides/marketplace/kat-overview).

## Slot filling

A **slot** is a piece of context KAT needs to answer correctly, such as a region, a product line, or a date. When a question is missing a required slot, KAT returns an `ASK_SLOT` outcome and the consumer interface prompts the end user for the missing information. Slots are preserved across turns through `AgentContext`.

See [Disambiguation and slot filling](/guides/marketplace/kat-overview#disambiguation-and-slot-filling).

## Disambiguation outcomes

Every KAT decision resolves to one of four outcomes:

* `CALL_KB`: route the query to one or more specific knowledge bases.
* `ASK_SLOT`: ask the end user for missing context.
* `BLOCKED`: refuse the query because it violates a guardrail.
* `OUT_OF_SCOPE`: refuse the query and list what the application can help with instead.

## Layout

A **layout** is the high-level shape of the consumer interface. Marketplace provides four layouts:

* **Chat**: conversational thread with citations and follow-up suggestions.
* **Search**: query box with ranked results and previews.
* **Structured**: form-style inputs that produce a structured output.
* **Hybrid**: chat plus a persistent structured panel.

See [Configure layouts](/guides/marketplace/configure-layouts).

## Component

A **component** is a visual primitive a knowledge application can render in addition to text. Marketplace provides six components:

* Comparison tables
* Content cards
* Timelines
* Progress trackers
* Coverage matrices
* Geolocation maps

Components are read-only and retrieval-oriented. See [Configure components](/guides/marketplace/configure-components).

## Operator and end user

An **operator** is a person who builds, configures, and publishes a deployment. An **end user** is a person who uses a published knowledge application. Operators authenticate to Marketplace itself (deployer authentication). End users authenticate per deployment (consumer authentication).

See [Deployer authentication](/guides/marketplace/deployer-auth) and [Consumer authentication overview](/guides/marketplace/consumer-auth-overview).

## Connector

A **connector** is the integration that ingests documents from a source system. Google Drive is the launch connector. Manual upload is also supported. See [Connectors overview](/guides/marketplace/connectors-overview).

## Evaluation

An **evaluation** is an automatic quality check that runs on publish. Marketplace generates test questions from the connected sources, asks the application to answer them, and scores responses on faithfulness and relevance. Results are visible from the deployment dashboard. See [Evaluations](/guides/marketplace/evaluations).


# Pinecone Marketplace
Source: https://docs.pinecone.io/guides/marketplace/overview

Pinecone Marketplace is a no-code platform for building, publishing, and operating grounded knowledge applications from vertical templates and connectors.

<Note>
  This feature is in [public preview](/release-notes/feature-availability).
</Note>

You start from a vertical template, connect the documents the application should use, and publish a polished consumer experience for your team or customers to ask questions and trust the answers.

<CardGroup>
  <Card title="Marketplace quickstart" icon="rocket" href="/guides/marketplace/quickstart">
    Pick a template, connect a folder of documents, and publish your first knowledge application.
  </Card>

  <Card title="Concepts" icon="book" href="/guides/marketplace/concepts">
    Learn the core concepts: deployments, templates, manifests, KAT, layouts, and components.
  </Card>
</CardGroup>

## What you can do

* Stand up a domain-specific knowledge application without writing application code.
* Ground every answer in your documents, with citations to the exact source.
* Compose multiple knowledge domains into a single application using the Knowledge Agent Toolkit (KAT).
* Publish in versioned releases with staged edits, automatic evaluation, and rollback.
* Control access with deployer authentication and per-deployment consumer authentication.
* Sync from sources you already use, starting with Google Drive.

## Who Marketplace is for

* **Operators** are the people who build, configure, and publish a knowledge application. Operators are usually technical program managers, IT leads, solutions architects, or operations managers. They prefer config-driven workflows over custom code.
* **End users** are the consumers of a published knowledge application. End users do not need a Pinecone account or knowledge of the underlying infrastructure. They sign in to the application and ask questions.

## What makes a knowledge application different

Every answer in Marketplace traces back to a source. The application knows what it knows and is built to say so when a question falls outside its scope. Operators do not have to assemble ingestion, retrieval, evaluation, authentication, or a consumer interface from scratch.

## How it works

1. **Start from a template.** Pick an app designed for a common knowledge application use case (HR Benefits, Customer Support, Sales Enablement, and others). The template ships with a tuned system prompt, recommended layout, and suggested visual components.
2. **Customize behavior.** Add your instructions, connect documents, and choose access settings for your use case.
3. **Deploy and iterate.** Publish quickly, share with your team, test usage, and improve your app over time.

Under the hood, a knowledge application is built from one or more Pinecone assistants. Marketplace orchestrates them through KAT, a routing and disambiguation layer that selects the right knowledge domain, asks for missing context when a question is ambiguous, and applies guardrails. The result is a multi-domain application that behaves like a single, coherent product.

```mermaid theme={null}
flowchart LR
    Sources[Connected sources] --> Ingest[Ingestion and indexing]
    Ingest --> KB[Knowledge bases per domain]
    KB --> KAT[KAT orchestration]
    KAT --> App[Consumer application]
    App --> User[End user or agent]
```

## Learn more

<CardGroup>
  <Card title="Templates" icon="grid" href="/guides/marketplace/templates-overview">
    Browse the bundled vertical templates and their recommended sources.
  </Card>

  <Card title="KAT" icon="route" href="/guides/marketplace/kat-overview">
    Learn how multi-domain routing, disambiguation, slot filling, and guardrails work.
  </Card>

  <Card title="Pricing and limits" icon="tag" href="/guides/marketplace/pricing-and-limits">
    Understand how Marketplace usage is billed and what limits apply.
  </Card>
</CardGroup>


# Marketplace pricing and limits
Source: https://docs.pinecone.io/guides/marketplace/pricing-and-limits

How Pinecone Marketplace usage is billed through Assistant and index consumption, plus deployment limits on connectors, files, and consumer auth.

<Note>
  This feature is in [public preview](/release-notes/feature-availability).
</Note>

This page describes how Pinecone Marketplace usage is billed and the limits that apply to a deployment.

## Pricing

Marketplace is bundled with your Pinecone usage. There is no separate Marketplace subscription. You pay for the Pinecone Assistant and index usage that your deployments generate, including:

* Assistant API usage from publishing, introspection, and end-user queries.
* Index storage and read or write units consumed by ingested documents.
* Pinecone Inference usage for any embedding or reranking your deployments perform.

For details on Pinecone Assistant pricing, see [Assistant pricing and limits](/guides/assistant/pricing-and-limits). For database pricing, see [Understanding cost](/guides/manage-cost/understanding-cost).

## Limits

The following limits apply to a deployment.

| Limit                             | Value                                                                                                   |
| --------------------------------- | ------------------------------------------------------------------------------------------------------- |
| Connectors per deployment         | Google Drive, manual upload                                                                             |
| Maximum file size per upload      | Matches Pinecone Assistant file limits                                                                  |
| Knowledge bases per deployment    | Multi-knowledge-base supported through the Knowledge Agent Toolkit (KAT)                                |
| Versions retained per deployment  | All published versions are retained for rollback                                                        |
| Consumer authentication providers | `link`, Google sign-in                                                                                  |
| Component types                   | 6 (comparison tables, content cards, timelines, progress trackers, coverage matrices, geolocation maps) |

For Pinecone Assistant file size and quantity limits, see [Assistant limits](/reference/api/assistant/assistant-limits).

## Access

Marketplace is available to all Pinecone organizations during public preview. Sign in at [marketplace.pinecone.io](https://marketplace.pinecone.io) with your Pinecone account.


# Marketplace quickstart
Source: https://docs.pinecone.io/guides/marketplace/quickstart

Pinecone Marketplace quickstart: pick a template app, connect a Google Drive folder, configure the deployment, and publish your first knowledge app.

<Note>
  This feature is in [public preview](/release-notes/feature-availability).
</Note>

This quickstart shows you how to publish your first knowledge application in Pinecone Marketplace. You will pick a template, connect a folder of documents, configure the application, and share it with end users.

You should be able to complete this quickstart in under an hour.

## Before you begin

* A Pinecone account. If you do not have one, [sign up](https://app.pinecone.io/?sessionType=signup).
* A folder of source documents in Google Drive that you want the application to answer questions about.

## 1. Open Marketplace

Go to [marketplace.pinecone.io](https://marketplace.pinecone.io) and sign in. If you already have a Pinecone account, you can also open Marketplace from the **Marketplace ↗** entry in the Pinecone console sidebar.

## 2. Pick an app

The **Apps** tab shows the available apps. Pick the one that most closely matches your use case and select **Get started** on the card. For the full list, see [App catalog](/guides/marketplace/template-catalog).

If none of the apps match exactly, pick the closest fit. Apps are starting points; you control the operating parameters and the documents the application uses.

## 3. Choose where to deploy

Marketplace prompts you to select the Pinecone organization and project where the app's assistant will be created. The assistant counts toward that project's plan limits. Pick the project, then select **Continue**.

## 4. Configure the deployment

The setup wizard prompts you for:

* A name and short description for the knowledge application.
* Operating parameters that shape responses, such as tone, system prompt, and the layout the consumer experience uses.

The project you chose in step 3 is shown for reference. You can change the name, description, and operating parameters later from the deployment dashboard. For details, see [Configure operating parameters](/guides/marketplace/configure-operating-parameters).

## 5. Connect a data source

Connect a Google Drive folder so the application has documents to answer from. Marketplace mirrors selected files, ingests them into Pinecone, and keeps them in sync as the source folder changes.

For step-by-step instructions, see [Connect Google Drive](/guides/marketplace/connectors-overview#connect-google-drive). To upload files directly instead, see [Manual uploads](/guides/marketplace/connectors-overview#manual-uploads).

## 6. Publish

Click **Publish**. Marketplace provisions the underlying Pinecone assistants in the background, runs introspection to build a capability manifest, generates suggested starter questions, and runs an automatic evaluation. Publishing is non-blocking: you can navigate away and return when the deployment is active.

For details, see [Publish a deployment](/guides/marketplace/publish-a-deployment).

## 7. Share with end users

Choose how end users access the application:

* **Link access**: anyone with the link can use the application.
* **Google sign-in**: end users sign in with Google.

Copy the deployment URL from the dashboard and share it. End users see a clean, branded interface with chat, citations, and any visual components you configured.

For details, see [Consumer authentication overview](/guides/marketplace/consumer-auth-overview).

## If you get stuck

Use the **Support** link in the Marketplace header to reach the Pinecone support team. The header also has a theme toggle and your account menu.

## Next steps

* Review answers and feedback in [Analytics and event logs](/guides/marketplace/analytics-and-event-logs).
* Add a second knowledge domain to the same deployment to take advantage of [multi-domain routing](/guides/marketplace/multi-domain-routing).
* Iterate on operating parameters or sources, then publish a new version. See [Manage versions and rollback](/guides/marketplace/manage-versions-and-rollback).


# Template catalog
Source: https://docs.pinecone.io/guides/marketplace/template-catalog

Browse the vertical apps in the Pinecone Marketplace template catalog, including Customer Support, HR Benefits, Deal Desk, and Financial Filings Analyzer.

<Note>
  This feature is in [public preview](/release-notes/feature-availability).
</Note>

Pinecone Marketplace ships with the following apps. Pick the one that most closely matches your use case. For how apps and templates work, see [Templates overview](/guides/marketplace/templates-overview).

## Customer Support

Resolve product questions and technical issues with help center content and troubleshooting runbooks.

* **Recommended layout**: chat
* **Suggested sources**: product docs, FAQs, resolved support tickets
* **Suggested components**: content cards, comparison tables

## Deal Desk

Guide pricing, discount approvals, and contract exceptions with your deal desk policies and approval matrices.

* **Recommended layout**: structured
* **Suggested sources**: pricing playbooks, discount policies, approval matrices
* **Suggested components**: comparison tables, coverage matrices

## Event Management

Help attendees navigate schedules, sessions, venue details, and day-of logistics from official event materials.

* **Recommended layout**: hybrid
* **Suggested sources**: agendas, speaker bios, venue maps, FAQs
* **Suggested components**: timelines, geolocation maps

## Financial Filings Analyzer

Analyze SEC filings and investor materials to extract KPIs, flag risks, and explain reporting changes.

* **Recommended layout**: search
* **Suggested sources**: 10-K and 10-Q filings, earnings transcripts, investor decks
* **Suggested components**: comparison tables, timelines

## HR Benefits

Help employees understand eligibility, enrollment, coverage, leave, and HR procedures from official benefits documentation.

* **Recommended layout**: chat
* **Suggested sources**: benefits guides, plan documents, policy handbooks
* **Suggested components**: comparison tables, coverage matrices

## Legal Document Search

Search pleadings, discovery, authority research, and damages materials to answer case questions quickly.

* **Recommended layout**: search
* **Suggested sources**: pleadings, discovery materials, contracts, prior briefs
* **Suggested components**: content cards, comparison tables

## Local Government Citizen Engagement

Help residents find city services, permit requirements, community programs, and official guidance.

* **Recommended layout**: chat
* **Suggested sources**: government websites, ordinances, service guides
* **Suggested components**: content cards, geolocation maps

## Onboarding and Training

Guide new hires through onboarding plans, role training, internal tools, and company policies.

* **Recommended layout**: chat
* **Suggested sources**: onboarding handbooks, role guides, training materials
* **Suggested components**: progress trackers, content cards

## Sales Enablement

Give reps fast answers on product, pricing, competition, positioning, and objection handling.

* **Recommended layout**: hybrid
* **Suggested sources**: pitch decks, battle cards, win-loss reports, customer summaries
* **Suggested components**: comparison tables, content cards


# Templates overview
Source: https://docs.pinecone.io/guides/marketplace/templates-overview

How Pinecone Marketplace templates work, what they define, and how operators customize a deployment after creating it from a template.

<Note>
  This feature is in [public preview](/release-notes/feature-availability).
</Note>

A template is a vertical configuration that bundles operating parameters, a recommended layout, suggested sources, and starter prompts for a specific use case. Templates compress the time from picking a use case to publishing a working knowledge application.

For the full list, see [Template catalog](/guides/marketplace/template-catalog).

## How resolution works

When you create a deployment from a template, Marketplace resolves configuration in three layers:

1. **Framework defaults**: baseline values that apply to every knowledge application.
2. **Vertical config**: values defined by the template, such as the system prompt, recommended layout, and starter prompts.
3. **Operator inputs**: values you provide in the setup wizard. These override the template defaults.

Each layer can override the previous one. Most operators only need to set values in the wizard.

## What a template defines

A template defines:

* The recommended consumer layout (chat, search, structured, or hybrid).
* A system prompt and operating parameters tuned for the vertical.
* Suggested visual components for the consumer interface.
* Starter prompts that surface to end users on the empty state.
* Recommended source types and structure.

A template does not define:

* The actual documents the application uses; you connect those during setup.
* The deployment name, description, or branding.
* Access policies; you choose those during setup or in the dashboard.

## Choosing a template

Pick the template that most closely matches the use case. If none match exactly, pick the closest fit and override the operating parameters. The choice of template does not lock you into a vertical; it only sets the initial configuration.

## Customize a deployment after creating it

A template is a starting point. After creating a deployment, you can override most template defaults from the deployment dashboard.

### What you can customize

The setup wizard and the deployment dashboard let you change:

* The name, description, and branding of the knowledge application.
* The system prompt and operating parameters that shape responses. See [Configure operating parameters](/guides/marketplace/configure-operating-parameters).
* The consumer layout. See [Configure layouts](/guides/marketplace/configure-layouts).
* Which visual components the application can render. See [Configure components](/guides/marketplace/configure-components).
* The connected sources and how they sync. See [Connectors](/guides/marketplace/connectors-overview).
* Starter prompts shown to end users on the empty state.
* Access policy, including the consumer authentication provider.

### What requires a new template

Structural changes that go beyond wizard inputs, such as defining a brand new vertical that other deployments will reuse, are handled by introducing a new template configuration. Operator-level template authoring is not supported.

### Edit and republish flow

1. Open the deployment dashboard.
2. Make your changes. Marketplace creates a new building version automatically when you edit an active deployment.
3. Publish the building version. Marketplace runs background provisioning, introspection, and evaluation. The previous version remains active until the new one is ready.
4. If a new version regresses, roll back from the version history. See [Manage versions and rollback](/guides/marketplace/manage-versions-and-rollback).

<Tip>
  Make small changes between publishes so that evaluations and end-user feedback give you a clear signal about what changed.
</Tip>


# Deploy Nexus BYOC
Source: https://docs.pinecone.io/guides/nexus/byoc/deploy

Install and operate Pinecone Nexus in your own cloud account.

<Note>
  Nexus BYOC is available only on [Enterprise plans](https://www.pinecone.io/pricing/).
</Note>

For architecture, see the [Nexus BYOC overview](/guides/nexus/byoc/overview). For data residency and limits, see [Data residency and limits](/guides/nexus/byoc/reference).

## Prerequisites

Before deploying Nexus BYOC, ensure you have the following tools installed on the machine that runs the install:

| Tool         | Purpose                         | Install                                                                      |
| ------------ | ------------------------------- | ---------------------------------------------------------------------------- |
| Git          | Clone the deployment repository | [git-scm.com](https://git-scm.com/downloads)                                 |
| Python 3.12+ | Runtime                         | [python.org](https://www.python.org/downloads/)                              |
| uv           | Package manager                 | [docs.astral.sh/uv](https://docs.astral.sh/uv/getting-started/installation/) |
| Pulumi       | Infrastructure-as-code          | [pulumi.com/docs/install](https://www.pulumi.com/docs/install/)              |
| kubectl      | Cluster access                  | [kubernetes.io](https://kubernetes.io/docs/tasks/tools/)                     |

You also need:

* The CLI for your cloud provider:
  * **AWS**: [AWS CLI v2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)
  * **GCP**: [gcloud CLI](https://cloud.google.com/sdk/docs/install), plus the `gke-gcloud-auth-plugin` component (`gcloud components install gke-gcloud-auth-plugin`)
  * **Azure**: [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli)
* A **dedicated cloud account** with admin-level permissions, used only for this deployment:
  * **AWS**: a dedicated account with `AdministratorAccess`. The installer creates IAM roles and policies, so `PowerUserAccess` is not sufficient.
  * **GCP**: a dedicated project with `roles/owner` and billing enabled. The installer creates IAM service accounts and bindings, so `roles/editor` is not sufficient.
  * **Azure**: a dedicated subscription with `Owner`. The installer creates managed identities and role assignments, so `Contributor` is not sufficient.
* A **Pinecone API key** from the Pinecone console.
* A Pinecone **Enterprise plan** (required for BYOC access).
* A **generation-LLM key**. Every model Nexus uses is BYOM and configurable through the model catalog: generation, embedding, and rerank. The catalog is backed by [LiteLLM](https://docs.litellm.ai/docs/providers), so you can bring any model any LiteLLM-supported provider offers, referenced by its LiteLLM `provider/model` identifier. The shipped defaults route generation to Google Gemini (get a key from [Google AI Studio](https://aistudio.google.com/apikey)) and route embedding and rerank to Pinecone-hosted models (no extra key). You can repoint any tier at a different provider (including endpoints inside your own boundary), each with its own key. Which model each call reaches determines where the content of that call goes. See [Data flows and residency](/guides/nexus/byoc/reference#data-flows-and-residency).
* A **Pulumi state backend** (either Pulumi Cloud or local state via `pulumi login --local`).
* Sufficient cloud quota for the resources (the setup wizard validates this).

Confirm these environment inputs before you start:

* **Region and three availability zones (AZs).** Deploy across three AZs, the supported high-availability shape. The generation-model provider you choose must be available in the region.
* **A spare private IP range** (RFC 1918, `/16` to `/20`) that does not overlap your existing networks. This becomes the Nexus virtual network.
* **Where your source data lives.** Know where your corpus resides so you can stage it into a context after install.
* **Egress paths.** Nexus makes outbound connections for the control-plane callback, metrics and traces, container image pulls, and calls to the inference models you configure. What content those model calls carry depends on how you configure your models. See [Data flows and residency](/guides/nexus/byoc/reference#data-flows-and-residency).

<Note>
  If you install any new tools, open a new terminal session before proceeding so that your shell picks up the updated PATH and environment.
</Note>

## 1. Deploy

To deploy Nexus BYOC, follow these steps.

<Steps>
  <Step title="Authenticate">
    The setup script checks your credentials but does not log you in, so authenticate to your cloud and to Pulumi first.

    <Tabs>
      <Tab title="AWS">
        ```bash theme={null}
        aws configure                  # or: aws sso login / exported AWS_* env vars
        aws sts get-caller-identity    # verify
        pulumi login                   # or: pulumi login --local
        ```
      </Tab>

      <Tab title="GCP">
        ```bash theme={null}
        gcloud auth login
        gcloud auth application-default login
        pulumi login                   # or: pulumi login --local
        ```
      </Tab>

      <Tab title="Azure">
        ```bash theme={null}
        az login
        az account show                # verify
        pulumi login                   # or: pulumi login --local
        ```
      </Tab>
    </Tabs>

    If you use the local Pulumi backend, choose a passphrase for encrypting stack secrets and export it as `PULUMI_CONFIG_PASSPHRASE`. Every `pulumi` command needs it.
  </Step>

  <Step title="Run the setup wizard">
    Clone the deployment repository and run the bootstrap script from the clone. The generated project is created next to the clone and depends on it.

    ```bash theme={null}
    git clone https://github.com/pinecone-io/pulumi-pinecone-nexus-byoc.git
    bash pulumi-pinecone-nexus-byoc/bootstrap.sh --cloud gcp
    ```

    Use `--cloud aws` or `--cloud azure` for the other clouds, and `--stack-name <name>` to name the Pulumi stack (default: `prod`).

    The script selects your cloud provider, checks that required tools are installed, verifies your cloud credentials, prompts for the project directory and name, then launches an interactive wizard that collects your configuration, validates your quotas, and generates a Pulumi project in an adjacent directory (default: `pinecone-nexus-byoc`). No cloud resources are created during this step.

    <Accordion title="Setup wizard prompts">
      The wizard prompts you for the following:

      | Prompt                         | Description                                                                                                                                             |
      | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
      | **Cloud provider**             | AWS, GCP, or Azure (skipped if pre-selected via `--cloud`).                                                                                             |
      | **Project directory and name** | Where to generate the Pulumi project. Defaults to `pinecone-nexus-byoc`.                                                                                |
      | **Pinecone API key**           | Your API key from the Pinecone console (or uses `PINECONE_API_KEY`).                                                                                    |
      | **Cloud credentials**          | Validates credentials and displays your account/project/subscription ID.                                                                                |
      | **Region**                     | Region for deployment.                                                                                                                                  |
      | **Availability zones**         | Three zones for high availability.                                                                                                                      |
      | **VPC/VNet CIDR block**        | Private IP range for the deployment. Choose a `/16` to `/20` that doesn't overlap existing networks.                                                    |
      | **Generation-LLM key**         | The default catalog's Gemini API key (BYOM).                                                                                                            |
      | **Network access**             | Public access. Private-only access is not supported for Nexus. See [Limitations](/guides/nexus/byoc/reference#limitations).                             |
      | **Deletion protection**        | Whether to protect storage and database resources from accidental deletion. Enable to guard against teardown mistakes. Disable before `pulumi destroy`. |
      | **Preflight checks**           | Validates cloud quotas. If checks fail, request quota increases before proceeding.                                                                      |
      | **Pulumi backend**             | Local (`~/.pulumi` with passphrase) or Pulumi Cloud.                                                                                                    |
    </Accordion>

    After completing the wizard, a Pulumi project is generated in your project directory. To change configuration later, edit `Pulumi.<stack>.yaml` and run `pulumi up`.
  </Step>

  <Step title="Deploy the infrastructure">
    Deploy the generated Pulumi project to create your cloud resources:

    ```bash theme={null}
    cd pinecone-nexus-byoc
    pulumi up
    ```

    Pulumi shows a preview of all resources to be created. Confirm to proceed. Provisioning time depends on the cloud:

    | Cloud | Typical provisioning time |
    | ----- | ------------------------- |
    | GCP   | 25 to 30 minutes          |
    | AWS   | 25 to 40 minutes          |
    | Azure | about 35 minutes          |

    When complete, the output displays:

    * The `update_kubeconfig_command` for configuring cluster access.
    * Your BYOC **environment name**.
    * Two workspace console links, printed once the first-run `default` workspace reaches `Ready`:
      * `nexus_default_workspace_data_console_url`: the workspace console for the `default` workspace, served from your deployment (where you work with contexts and run queries).
      * `nexus_default_workspace_control_console_url`: the Pinecone Console page for that workspace.

    <Note>
      The first `pulumi up` creates a `default` workspace automatically and waits for it to become ready before printing the links. Later `pulumi up` runs never recreate or modify it.
    </Note>

    <Accordion title="Infrastructure provisioned">
      The deployment creates the following in your cloud account:

      | Component            | AWS                                                             | GCP                                           | Azure                                    |
      | -------------------- | --------------------------------------------------------------- | --------------------------------------------- | ---------------------------------------- |
      | **VPC / Networking** | VPC, public and private subnets, NAT gateways, internet gateway | VPC network, subnets, Cloud NAT, Cloud Router | VNet, subnets, NAT gateway               |
      | **Kubernetes**       | EKS cluster with managed node groups                            | GKE cluster with node pools                   | AKS cluster with agent pools             |
      | **Object storage**   | S3 buckets (corpus, knowledge artifacts, data, WAL, backups)    | GCS buckets                                   | Blob Storage containers                  |
      | **Metadata store**   | FoundationDB (Nexus metadata)                                   | FoundationDB                                  | FoundationDB                             |
      | **Load balancing**   | Network Load Balancer                                           | Internal load balancer                        | Internal load balancer                   |
      | **DNS**              | Route 53 hosted zone                                            | Cloud DNS managed zone                        | Azure DNS zone                           |
      | **TLS certificates** | AWS Certificate Manager                                         | cert-manager                                  | cert-manager                             |
      | **IAM**              | IAM roles and policies                                          | Service accounts and Workload Identity        | Managed identities and Workload Identity |

      The cluster comes up small and then autoscales across several node pools spread over the three AZs. See [Cluster footprint](/guides/nexus/byoc/reference#cluster-footprint) for the node pools.
    </Accordion>
  </Step>

  <Step title="Verify the deployment">
    Configure `kubectl` using the `update_kubeconfig_command` from the deployment output:

    <Tabs>
      <Tab title="AWS">
        ```bash theme={null}
        aws eks update-kubeconfig --region <region> --name <cluster-name>
        ```
      </Tab>

      <Tab title="GCP">
        ```bash theme={null}
        gcloud container clusters get-credentials <cluster-name> --region <region> --project <project-id>
        ```
      </Tab>

      <Tab title="Azure">
        ```bash theme={null}
        az aks get-credentials --resource-group <resource-group> --name <cluster-name>
        ```
      </Tab>
    </Tabs>

    Cluster access is for administrative tasks like viewing operations and troubleshooting. Everyday work (creating contexts, curating sources, and running queries) uses the Nexus console, CLI, or API.

    Verify all components are running:

    ```bash theme={null}
    kubectl get pods -A | grep -E "(pinecone|pc-|nexus)"
    ```

    All pods should show `Running` status. If any are in `Pending` or `CrashLoopBackOff`, see [Troubleshooting](#troubleshooting).
  </Step>
</Steps>

## 2. Use

Once your deployment is up and the `default` workspace is ready, you work with Nexus the same way you would in the managed service. For the end-to-end lifecycle (create a context, stage sources, curate, and query with KnowQL), see the [Nexus quickstart](/guides/nexus/quickstart).

Two things are specific to BYOC:

* **Point your client at your own workspace host.** Instead of the Pinecone-hosted endpoint, use your deployment's workspace host, the base of `nexus_default_workspace_data_console_url` from the deployment output. For the CLI, pass it as `--api-url`:

  ```bash theme={null}
  nexus login --api-url https://default-<vault>.wksp.<environment>.pinecone.io --api-key "$PINECONE_API_KEY"
  ```

  Authentication uses your Pinecone API key, and the tenancy boundary is the workspace's Pinecone project.

* **A `default` workspace is created on the first `pulumi up`.** The install creates it automatically and prints its data console URL (served from your deployment) and its Pinecone Console URL. Later `pulumi up` runs never recreate or modify it.

## 3. Manage

<Note>
  Deploying a BYOC environment creates an internal project named `__SLI__` in your organization. Pinecone uses it to enforce SLAs for your BYOC environment. Do not modify or delete it.
</Note>

### Operations and upgrades

Pinecone uses a pull-based model for cluster operations:

1. When upgrades, scaling, or maintenance are needed, Pinecone queues operations in the control plane.
2. An agent running in your cluster (deployed automatically during setup) continuously pulls pending operations.
3. Operations execute locally within your cluster.
4. Status is reported back to Pinecone for monitoring.

This model ensures Pinecone never needs direct access to your infrastructure. All communication is outbound from your cluster.

A deployment is pinned to two independent image tags that roll separately: `pinecone-version` (the Pinecone Database images) and `nexus-version` (the Nexus images). The two pins are unrelated. Bumping one does not touch the other. Pinecone manages upgrades in the background. To trigger one manually, set either pin (or both) to your target version (for example, `main-abc1234`) and re-run `pulumi up`:

```bash theme={null}
# Bump the Pinecone Database version
pulumi config set pinecone-version <new-db-tag>
pulumi up

# Bump the Nexus version
pulumi config set nexus-version <new-nexus-tag>
pulumi up
```

### Monitoring

You can monitor your deployment through multiple channels:

<AccordionGroup>
  <Accordion title="Pinecone console">
    View workspace and index metrics in the Pinecone console. Control plane operations and metrics work regardless of your network access mode.
  </Accordion>

  <Accordion title="Prometheus">
    To use Prometheus, configure your monitoring tool within your VPC to scrape metrics from the cluster. Your Prometheus instance must have network access to the BYOC VPC. The deployment output includes the metrics endpoint URL and port.
  </Accordion>

  <Accordion title="Audit logs">
    Cluster operations are persisted as Kubernetes CRDs for compliance and auditing:

    ```bash theme={null}
    kubectl get cluster-operations
    ```
  </Accordion>
</AccordionGroup>

### Cleanup

<Warning>
  Delete all Nexus workspaces before destroying the cluster. Resources cannot be properly terminated if the cluster is destroyed first.
</Warning>

To destroy your deployment:

```bash theme={null}
# 1. Delete all workspaces via the Pinecone console
# 2. Then destroy the infrastructure
pulumi destroy
```

If `deletion-protection` is enabled (the default), you must either disable it in `Pulumi.<stack>.yaml` and run `pulumi up`, or manually delete the protected storage and database resources via the cloud console before running `pulumi destroy`.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Preflight check failures">
    The setup wizard validates cloud quotas before deployment. If checks fail:

    | Check                                | Resolution                                                                                    |
    | ------------------------------------ | --------------------------------------------------------------------------------------------- |
    | VPC / network quota                  | Request a limit increase via your cloud provider's quota console                              |
    | Kubernetes cluster quota             | Request an EKS, GKE, or AKS cluster limit increase                                            |
    | IP address quota                     | Release unused IPs or request a limit increase                                                |
    | Instance / machine type availability | Verify the required type is available in your region                                          |
    | vCPU quota                           | Request a regional vCPU increase                                                              |
    | Required APIs / providers            | Enable the cloud APIs (GCP) or register the resource providers (Azure) the installer requires |
  </Accordion>

  <Accordion title="Deployment failures">
    If `pulumi up` fails partway through:

    ```bash theme={null}
    pulumi refresh  # Sync state with actual resources
    pulumi up       # Retry deployment
    ```

    On AWS, the slowest single step is VPC endpoint service private DNS verification: roughly 15 minutes of `Waiting for domain verification (pendingVerification)` polling is normal, not a hang. Let it finish.
  </Accordion>

  <Accordion title="Cluster access issues">
    Ensure your cloud credentials match the account where the cluster is deployed:

    <Tabs>
      <Tab title="AWS">
        ```bash theme={null}
        aws sts get-caller-identity
        ```
      </Tab>

      <Tab title="GCP">
        ```bash theme={null}
        gcloud auth list
        gcloud config get-value project
        ```
      </Tab>

      <Tab title="Azure">
        ```bash theme={null}
        az account show
        ```
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="Workspace stuck initializing">
    The first-run `default` workspace is created asynchronously and becomes ready only once the Nexus services in your deployment are up. If `pulumi up` times out waiting for it, re-run `pulumi up` once the cluster pods are `Running`. If it remains stuck, contact [Pinecone support](https://app.pinecone.io/organizations/-/settings/support/ticket).
  </Accordion>
</AccordionGroup>

For additional help, see the [GitHub Issues](https://github.com/pinecone-io/pulumi-pinecone-nexus-byoc/issues) for the deployment repository.


# Nexus BYOC overview
Source: https://docs.pinecone.io/guides/nexus/byoc/overview

What Nexus bring your own cloud is, how it relates to Database BYOC, and its architecture.

<Note>
  Nexus BYOC is available only on [Enterprise plans](https://www.pinecone.io/pricing/).
</Note>

Pinecone Nexus compiles your enterprise data into queryable knowledge that AI agents retrieve with a single [KnowQL](/guides/nexus/concepts#knowql) query. Nexus BYOC (bring your own cloud) is a single installer that deploys both Nexus and the Pinecone Database data plane it runs on, entirely inside your own cloud account (AWS, GCP, or Azure). You do not install Database BYOC separately. Nexus BYOC includes it (see [how the two relate](#how-nexus-byoc-relates-to-database-byoc)).

Nexus BYOC is designed for organizations with strict requirements around data sovereignty, network isolation, and data residency. You get the benefits of a managed service (upgrades, scaling, and maintenance) without giving up control of your data or infrastructure.

Pinecone never has direct access to your cloud account, and no inbound network access is required. Components in your cluster pull operations from Pinecone and execute them locally. Your sources and compiled knowledge are stored within your account. Data leaves your account through the inference calls Nexus makes to curate and answer, plus operational telemetry (no customer content). Those inference calls carry the content being processed to the model endpoints used for each step. Models are configurable (BYOM). Generation always uses the provider you configure, and by default embedding and rerank run on Pinecone-hosted models, so with the defaults some document and query text is sent to Pinecone for those steps. See [Data flows and residency](/guides/nexus/byoc/reference#data-flows-and-residency) for the exact breakdown, and read it before making residency commitments.

Nexus BYOC uses a split architecture:

* The **data plane** runs entirely in your cloud account within a dedicated virtual network (a VPC on AWS and GCP, a VNet on Azure): the Nexus services, the Pinecone Database data plane they depend on, a metadata store, and object storage for your corpus and derived knowledge artifacts. This is where your sources are curated, indexed, and queried.
* The **control plane** is managed by Pinecone globally and handles workspace lifecycle, authentication, billing, and user management, but never stores or processes your data.

For maintenance, an agent in your cluster authenticates with Pinecone's control plane, pulls pending operations (upgrades, scaling, and so on), and executes them locally. Only operational metrics (CPU, memory, latency) and traces are transmitted to Pinecone for monitoring. Customer data is filtered out before transmission.

## How Nexus BYOC relates to Database BYOC

Nexus BYOC is installed from a single repository, [`pulumi-pinecone-nexus-byoc`](https://github.com/pinecone-io/pulumi-pinecone-nexus-byoc). One `pulumi up` deploys both the Nexus services and the Pinecone Database data plane they run on. There is no separate Database install to run first or alongside it.

The Pinecone Database data plane is deployed automatically because Nexus runs on it: it is the storage and retrieval engine beneath your contexts, not a separate product you operate. You work with a Nexus BYOC deployment through contexts and [KnowQL](/guides/nexus/concepts#knowql). Nexus BYOC brings one additional dependency: a generation-LLM key you supply (default: Google Gemini).

If you want a standalone Pinecone vector database in your own cloud instead, see [Database BYOC](/guides/production/bring-your-own-cloud), which has its own installer. The Database BYOC installer is not part of the Nexus install.

Nexus BYOC uses the core Nexus product terms (context, manifest, KnowQL, and workspace). See [Nexus concepts](/guides/nexus/concepts) for definitions, [Data residency and limits](/guides/nexus/byoc/reference) for the security and operational details, and [Deploy Nexus BYOC](/guides/nexus/byoc/deploy) to install.


# Data residency and limits
Source: https://docs.pinecone.io/guides/nexus/byoc/reference

Where your data lives and travels in Nexus BYOC, plus authentication, encryption, cluster footprint, and limitations.

<Note>
  Nexus BYOC is available only on [Enterprise plans](https://www.pinecone.io/pricing/).
</Note>

The security and operational details of a Nexus BYOC deployment: where your data stays and where it travels, how you authenticate and encrypt it, the cluster footprint, and the current limitations. For what BYOC is and how it is architected, see the [Nexus BYOC overview](/guides/nexus/byoc/overview).

## Data flows and residency

Nexus BYOC keeps your data at rest in your account, but, like any system that calls a language model, it must send the content being processed to whatever model serves each request. Understand this before making residency or compliance commitments.

**Stays in your cloud account (at rest):**

* Your uploaded sources.
* The compiled knowledge built from them: chunks and derived artifacts.
* The indexes that back your contexts and the Nexus metadata store.

These live in your object storage, database, and metadata store, inside your virtual network.

**Leaves your account, and where it goes:**

* **To Pinecone (control plane and observability):** operational metrics, traces, and cluster and operation status (for example, CPU, memory, and latency). *No customer content.* Customer data is filtered out before transmission.
* **To the inference models you configure:** the content being processed. Nexus calls models during curation (embedding your source text, and for artifact generation sending source text to the generation model) and during a query (sending the query text and the retrieved passages to the generation model, the query text to the embedding model, and candidate passages to the rerank model). Each such call carries that content to whichever provider serves the model:
  * With the shipped defaults, the generation model is an external provider you bring (Google Gemini by default, using your key), so source text (during artifact generation) and query text plus retrieved passages go to that provider. Embedding and rerank run on Pinecone-hosted models, so the text being embedded or reranked is sent to Pinecone.
  * **Every model is BYOM and configurable.** You choose the provider (and therefore the destination) for the generation, embedding, and rerank tiers independently. To keep all customer content inside your trust boundary, repoint each tier at a model you host or otherwise control. A residency-strict deployment does not have to use any Pinecone-hosted or third-party model.

<Warning>
  This differs from [Database BYOC](/guides/production/bring-your-own-cloud), where [integrated embedding](/guides/production/bring-your-own-cloud#limitations) is unsupported specifically so that document text never leaves your account. Nexus always performs an embedding step, so by default some document and query text is sent to Pinecone.
</Warning>

## Authentication and access

You authenticate to a BYOC deployment with Pinecone API keys. Nexus has no separate user model. Identity is delegated to Pinecone, and the tenancy boundary is the Pinecone project behind the workspace. Manage users and API keys in the Pinecone console.

## Encryption and customer-managed keys

In BYOC, your data (sources, compiled knowledge, index contents, and the metadata store) is stored in your cloud account, on object storage, databases, and block volumes you own. You apply your cloud provider's KMS to those resources using the same native controls you use for other workloads: key policies, rotation, and compliance programs such as PCI or ISO 27001. Where the installer supports supplying your own KMS key, you can provide it. See the [deployment repository's README](https://github.com/pinecone-io/pulumi-pinecone-nexus-byoc) for current options. This is not the console [CMEK](/guides/production/configure-cmek) flow used for hosted Pinecone projects. For how the two relate, see the Database BYOC page's [Encryption and customer-managed keys](/guides/production/bring-your-own-cloud#encryption-and-customer-managed-keys).

## Cluster footprint

Nexus BYOC runs a Kubernetes cluster across several dedicated node pools spread over three availability zones (AZs):

| Node pool                                                       | Purpose                                                  |
| --------------------------------------------------------------- | -------------------------------------------------------- |
| Pinecone Database                                               | The data plane, including query routing and index builds |
| Metadata store                                                  | Stores Nexus metadata, backed by FoundationDB            |
| Nexus services                                                  | The curation and query runtimes and their workflow jobs  |
| [Dedicated read nodes](/guides/index-data/dedicated-read-nodes) | Scale from zero as read demand grows                     |

The cluster comes up small and autoscales with load and with the number of contexts and indexes. Node counts and instance types change across releases as the footprint is tuned. Size your cloud quotas from the installer's preflight quota checks in [Deploy Nexus BYOC](/guides/nexus/byoc/deploy) rather than from a fixed node count.

## Limitations

* **The endpoint is public and authenticated.** The Nexus API and console are reached over a public, access-controlled endpoint. Private-only access (PrivateLink, Private Service Connect, or Private Endpoint) for Nexus is not supported. (The Pinecone Database data plane in the same deployment can run privately, but Nexus cannot.)
* **Domain and TLS are Pinecone-managed.** The endpoint is served on a Pinecone-managed domain (`.byoc.pinecone.io`) with certificates issued and renewed automatically. Custom or customer-owned domains are not supported, so no DNS delegation or certificate handoff is required from you.
* **Bring your own models.** Generation, embedding, and rerank are all BYOM and configurable. A generation-LLM key is required (default: Google Gemini). Provider quota is your responsibility, so size the tier to your ingest volume. Model configuration determines where content is sent. See [Data flows and residency](#data-flows-and-residency).
* **Workspace names are unique per Pinecone project.** When several deployments share one project, give each additional deployment a distinct workspace name via `nexus-default-workspace-name`.
* **Environment cap.** Each organization can create a limited number of BYOC environments. To request an increase, contact [Pinecone support](https://app.pinecone.io/organizations/-/settings/support/ticket).

To install, see [Deploy Nexus BYOC](/guides/nexus/byoc/deploy).


# Nexus key concepts
Source: https://docs.pinecone.io/guides/nexus/concepts

Learn the core Pinecone Nexus concepts: sources, workspaces, contexts, manifests, artifacts, tasks, sessions, and the Query API, and how they connect.

Pinecone Nexus compiles your data into queryable knowledge that AI agents reach through a single interface. This page defines the core concepts and how they fit together, from the sources you bring in to the answers agents get back. For a high-level diagram of how they connect, see [How Nexus works](/guides/nexus/how-it-works).

## Sources

Your data, wherever it lives: docs and wikis, databases, APIs and SaaS, object storage, event streams, code repos. Upload files directly, or import them through a *connector* (Box and Google Drive). Import and manage sources from a context's **Sources** tab, using **+ Import**.

## Workspace

The top-level container you work in. A workspace holds your contexts and the tasks that build and query them. It is backed by a Pinecone project, which provides identity and access and is the tenancy boundary. You can have more than one workspace, each with a name that is unique within its Pinecone project.

## Context

The unit of knowledge: *Sources → Manifest → Knowledge*. The manifest turns sources into knowledge. One context per dataset, and a query reads one or more. A context holds up to 10 GB across 100,000 files, with each file up to 250 MB.

## Manifest

Configuration, not code: the plan that turns sources into knowledge (what to chunk, embed, and distill into artifacts). Shape it on **Design**, and curation executes it. [More on context design](/guides/nexus/context-design).

## Tasks and workflows

A *task* runs a *workflow* in a sandbox. **Import** ingests and cleans sources, **Curate** builds artifacts per the manifest, **Explore** proposes a manifest from your sources, and **Optimize** self-tunes the manifest from real query traffic. **Search** answers a query via KnowQL. Each workflow may ensemble multiple models as needed. Track them, and watch curation and query spend, under **Activity**.

## Artifacts (the knowledge)

The condensed knowledge that curation produces. Each artifact has a *type* (its classification, shown in the console) and a *kind* (a config within the type), plus a scope and provenance, and can be linked to others by typed edges into a knowledge graph. Browse them by type on a context's **Knowledge** tab. [See the artifact reference](/guides/nexus/context-design#artifact-kinds).

## Query

The single interface into Pinecone Nexus. A *query* asks a question scoped to one or more curated contexts. Pinecone Nexus plans its own retrieval and answers with citations. Query a single context from its **Search this context** box, or drive it from your own code via the [Nexus API](/reference/api/nexus/introduction). See the [quickstart](/guides/nexus/quickstart#3-query-your-context).

## KnowQL

The declarative query language agents use to query Nexus. A KnowQL query names a `scope` (the contexts to read) and an `ask` (the question), plus an optional typed `shape` for structured output. Nexus plans and runs its own retrieval, then returns a grounded, cited answer. The Composable Retriever serves your artifacts through KnowQL, and the Context Compiler is what builds those artifacts during curation.

## Sessions

A multi-turn conversation. A single query is one turn: a question in, an answer out. A session keeps state across turns, so follow-up questions resolve against what came before, and it can draw on more than one context at once. Start one from the workspace **Home** or **Sessions > + New session**, or from a context's **Query** tab, where the **Search this context** box opens a session scoped to that context.

## Use

Query your contexts from other systems: an [MCP server](/guides/nexus/mcp-server) for Claude Desktop and other MCP clients, or the [Nexus API](/reference/api/nexus/introduction) over HTTP.


# Context design
Source: https://docs.pinecone.io/guides/nexus/context-design

The manifest, the information stack (chunks, artifacts, and edges), and the artifact-kind reference.

How a context is shaped: the manifest that drives it and the knowledge curation builds from your sources.

## The manifest

A context doesn't ship custom Python. Instead, one generic runtime reads a single validated JSON document, the *manifest*, that describes how this context should curate its sources into knowledge. Its main section, `curate`, defines how to build knowledge from the sources, what to chunk and embed and which artifacts to derive. Change the manifest, change the behavior. A never-tuned context still works, because the schema ships sane defaults.

On the **Design** page, let **Explore** propose a manifest from your sources (or start from a template), review it, then curate. Curation executes the manifest against the sources.

## The information stack

When Pinecone Nexus curates a context, it builds two layers of knowledge:

### Chunks

Sources are split into spans and embedded for hybrid (semantic + keyword) search. Content-addressed, so editing a document re-embeds only what changed. Every query can fall back to chunks.

### Artifacts

Artifacts sit above the chunks. Each artifact has a *type* and a *kind*, a *scope*, *provenance* linking back to its source chunks, and optional *edges*, which are typed, directed, source-cited relationships to other artifacts. The *type* is the artifact's classification, defined by your manifest and shown in the console (a template might define types such as Note, Concept, Entity, and Workstream). The *kind* is a built-in config within a type.

Corpus-scoped artifacts plus typed edges form a cross-document knowledge graph. Factual queries dive straight to chunks. Synthesizing or "connect-the-dots" queries enter at artifacts, walk the edges, then drill down to chunks for evidence.

## Artifact kinds

| Kind       | Scope         | Description                                                                    |
| ---------- | ------------- | ------------------------------------------------------------------------------ |
| `summary`  | corpus or doc | A condensed overview, of the whole corpus or a single document.                |
| `topic`    | corpus        | A theme or subject distilled across the sources.                               |
| `entity`   | corpus        | A named thing (account, person, product) with its relationships.               |
| `event`    | corpus        | Something that happened, often time-stamped, good for timelines and counts.    |
| `doc`      | per-document  | A per-document artifact, scoped to one source file.                            |
| `page`     | per-document  | A single source page, the finest grain, for exact quotes and figures.          |
| `glossary` | corpus        | A term-and-definition pair, collected across the corpus into a shared lexicon. |


# Curation
Source: https://docs.pinecone.io/guides/nexus/how-curation-works

The write path that turns sources into chunks and artifacts, incrementally, driven by the manifest.

Curation is how Pinecone Nexus turns a context's source documents into the chunks and artifacts that queries read from. One generic runtime, the Context Compiler, drives it, parameterized by the context's [manifest](/guides/nexus/context-design).

## Curate up front

Curation does the hard work *up front* so retrieval gets a head start at query time. Sources aren't just chopped into chunks. They're reorganized into typed artifacts (summaries, entities, events) connected by edges, with structure captured for exact answers.

<img alt="Sources curated by the runtime under a manifest into a knowledge tree of chunks, artifacts, edges, and structured tables" />

<img alt="Sources curated by the runtime under a manifest into a knowledge tree of chunks, artifacts, edges, and structured tables" />

## The curation runtime

A curate run is a single generic entrypoint the orchestrator launches for the context. There's no per-context code. Every context runs the same runtime, and the manifest decides what to chunk, embed, and extract. A run moves through these phases:

1. **Delta:** Hash every source and compare to the curation ledger to find what's new, changed, or deleted.
2. **Replay:** Add back any sources that share an artifact with a changed or deleted one, since their artifacts may need rewriting.
3. **Cleanup deletes:** Drop deleted sources from the knowledge tree and the index, and record the removal.
4. **Per-source curate:** For each source to process: chunk, embed into the index pair, and extract its document-scoped artifacts.
5. **Corpus aggregation:** A single pass derives cross-document artifacts and the typed, cited edges that connect them into a knowledge graph.
6. **Finalize:** Commit counts and usage, and the orchestrator copies the knowledge tree back to the context's store.

## Per-source steps

For each source the delta says to process, the runtime runs the same three steps:

* **Chunk:** The source is split into spans, format-aware, with size enforcement.
* **Embed:** Each span is embedded into the semantic (and optional keyword) index, ready for hybrid search.
* **Extract:** The manifest's document-scoped artifact types are distilled out of the source, each carrying provenance back to its chunks.

## Incremental curation

Curation never rebuilds the world unless you ask it to. It keeps a ledger of every source it has already processed, so a run only touches what actually changed:

* **Content-addressed:** Sources are tracked by content hash, so identical files are never re-processed.
* **Only what changed:** Editing a document re-embeds just the changed spans and re-extracts just that source, not the whole corpus.
* **Artifact-aware replay:** When a source feeding a shared artifact changes, the sources it connects to are replayed so edges stay consistent.

Need a clean slate? Curate with *force re-curate* to wipe the index and ledger and rebuild everything from scratch.

## Outputs

When a run finishes, the context has everything a query needs, on disk, in the index, and as queryable structure:

* **The knowledge tree:** Chunks plus condensed artifacts written under the context's knowledge store on disk.
* **The index pair:** Chunks land in the default namespace and artifacts in the artifacts namespace of the context's semantic index (keyword too, when enabled).
* **Structured tables:** A per-context SQLite mirror exposes typed artifact types as queryable tables, which queries reach for on counts and enumerations.
* **The curation ledger:** Every processed source is recorded, so the next run computes its delta against it instead of starting over.


# How Nexus works
Source: https://docs.pinecone.io/guides/nexus/how-it-works

How Nexus distills curated artifacts for retrieval, then answers with code over a retrieval SDK.

Most RAG systems chop documents into chunks and hope the right ones surface at query time. Pinecone Nexus does the hard work *up front*: it distills your sources into curated artifacts so the information an answer needs is already organized and easy to find, then answers questions by writing code over a retrieval SDK.

At a high level, your data flows through connectors into contexts, tasks curate each context into knowledge, and agents query it through a single KnowQL interface:

<img alt="Pinecone Nexus architecture: your data enters through connectors into a workspace of contexts and tasks, is curated into knowledge in a sandbox, then queried through KnowQL to serve your AI application." />

<img alt="Pinecone Nexus architecture: your data enters through connectors into a workspace of contexts and tasks, is curated into knowledge in a sandbox, then queried through KnowQL to serve your AI application." />

The rest of this page zooms into the two ideas that make that work: curated artifacts for retrieval, and answering with code.

## Curated artifacts

Raw chunks are noisy. The same fact is scattered across pages, counts require reading everything, and relationships are implicit. Curation reorganizes the corpus into artifacts, which are condensed, typed units of knowledge, so retrieval gets a head start.

<img alt="Raw chunks reorganized into curated artifacts" />

<img alt="Raw chunks reorganized into curated artifacts" />

* **Pre-computed, typed knowledge.** Curation produces artifacts by kind: summaries, topics, entities, events, per-doc and per-page units. Each is small, focused, and describes itself, so the right one is easy to retrieve.
* **Structure for exact answers.** Structured artifact types become queryable tables, so "how many" and "list every…" questions get exact answers instead of a guess from prose.
* **Relationships made explicit.** Edge types connect artifacts (who mentions what, what happened when), turning a flat pile of text into a graph you can walk.

## Answering with code

Curated artifacts are only half the story. At query time the model doesn't just stuff chunks into a prompt. It writes Python against a retrieval SDK to gather exactly the evidence it needs, then answers from that.

<img alt="Question to generated retrieval code over artifacts to evidence to answer" />

<img alt="Question to generated retrieval code over artifacts to evidence to answer" />

* **The model orchestrates retrieval.** One turn can read artifacts off disk, run semantic and keyword search, walk the relationship graph, and query structured tables, composing several operations instead of a single top-k lookup.
* **Only evidence enters the prompt.** Raw tool output stays in the code sandbox. Just the distilled evidence the agent selected reaches the model. That keeps context small and answers grounded, and every claim traces to a source.
* **It can iterate.** If the first pass isn't enough, the agent refines its code and searches again, so hard questions get more work, not a worse answer.

## Benefits

Distilling artifacts up front plus writing retrieval code at query time means higher-quality answers on large, messy corpora: exact counts, real relationships, and citations you can trust, without dumping everything into the model's context.


# Queries
Source: https://docs.pinecone.io/guides/nexus/how-queries-work

The query runtime that gathers evidence and composes a grounded, cited answer.

A query is a single turn: a question in, a grounded answer out. A multi-turn conversation is a session. Rather than stuffing raw chunks into a prompt, Pinecone Nexus runs an agent loop in which the model writes Python against a retrieval SDK to gather just the evidence it needs, then composes a grounded answer with citations.

<img alt="A query turn: the agent loops, writing code against a retrieval SDK to gather evidence, then composes a cited answer" />

<img alt="A query turn: the agent loops, writing code against a retrieval SDK to gather evidence, then composes a cited answer" />

## Retrieval as code

The usual ways to answer over a corpus both struggle. Agentic RAG issues many retrieval calls and burns tokens stitching them together, and a coding agent greps and parses raw files, which is powerful but slow, expensive, and unreliable.

A query turn does the hard retrieval work in one place. The model writes Python that reads artifacts, runs search, walks the graph, and queries structured tables, then answers from only the evidence it surfaced. Raw tool output never enters the model's context.

## The query runtime

A query is run by the Nexus runtime, a single generic Python image the orchestrator launches fresh for each turn. There is no per-context code. Every context runs the same entrypoint, parameterized by its [manifest](/guides/nexus/context-design).

1. **A fresh container per turn:** Each query spawns one isolated container that runs exactly that turn, then exits. It pulls the scoped contexts' curated knowledge: artifacts on disk plus their vector index.
2. **Orientation:** The runtime reads the manifests and an artifact outline up front, so the model starts knowing what knowledge exists and where.
3. **The agent loop:** The model writes Python into a persistent REPL to call the retrieval SDK, reading artifacts, running search, walking the graph, querying structured tables.
4. **Step events:** Each step is posted back as it happens, powering the live answer stream you see in the console. You can replay the full sequence for any query with [query tracing](/guides/nexus/query-tracing).
5. **Synthesis:** Once enough evidence is gathered, the runtime composes a grounded answer with inline citations, then finalizes the turn.

## The agent loop

The model's primary tool is `run_python`, a persistent REPL. Variables survive across calls, so the model chains operations together: find an artifact, read it, filter its sources, drill for a verbatim quote, all in one block. It processes results in code and prints only what it needs.

If the first pass misses, the model refines its code and searches again, so hard questions get more work, not a worse answer. The loop stops as soon as the model can answer.

```python theme={null}
# One turn: find an artifact, read it, drill its sources.
art = await search_knowledge("acquisition terms", kind="summary")
srcs = read_artifact(art[0].name).sources
for h in await search_in_sources(srcs, "purchase price"):
    print(h.fields["source_path"], "::", h.fields["chunk_text"][:160])
```

Independent searches run concurrently, and lookups already held in a variable are never repeated. The loop is capped, so the model is pushed to extract everything it needs and answer in a few steps.

## The retrieval SDK

The Composable Retriever pre-binds these primitives into the REPL. Read artifacts cheaply off disk, fall back to search over the index, and reach for SQL when the question is a count or enumeration.

### Read artifacts

| Primitive             | What it does                                       |
| --------------------- | -------------------------------------------------- |
| `outline_knowledge()` | a map of every artifact in the context             |
| `read_artifact(name)` | a condensed artifact: its body, edges, and sources |
| `read_rosters()`      | "all X" rosters for list-everything questions      |
| `describe_type(name)` | the full manifest spec for an artifact type        |

### Search

| Primitive                           | What it does                                               |
| ----------------------------------- | ---------------------------------------------------------- |
| `search_knowledge(query)`           | semantic search over artifacts (optionally by kind)        |
| `search_source(query)`              | semantic search over raw source chunks                     |
| `search_source_by_keyword(query)`   | lexical/BM25 for exact IDs, codes, and phrases             |
| `search_in_sources(sources, query)` | semantic search within a specific artifact's source chunks |
| `cite_from_artifact(name)`          | drill an artifact's sources for a verbatim span            |

### Structured tables

| Primitive          | What it does                                                                             |
| ------------------ | ---------------------------------------------------------------------------------------- |
| `query_db(sql)`    | read-only SQL over typed artifact tables, the first resort for how-many / counts / per-X |
| `walk_graph(name)` | an N-hop subgraph around an artifact, following typed edges                              |

## Synthesis

**Synthesis from surfaced evidence.** The answer is composed from just the evidence the code surfaced, never the raw corpus, so the model reasons over a small, relevant context instead of the whole document set.

**Citations that trace to a source.** Inline citation markers map back to real source spans: the file, page, and verbatim text behind every claim.

**Optional structured output.** When a `shape` is supplied, the answer is routed through structured synthesis to produce a schema-conforming document instead of prose.


# MCP server
Source: https://docs.pinecone.io/guides/nexus/mcp-server

Query your Pinecone Nexus contexts from any Model Context Protocol client, such as Claude Desktop, over Streamable HTTP.

The Nexus MCP server exposes three read-only tools, `list_contexts`, `query_context`, and `get_query`, over Streamable HTTP at your deployment's workspace host with the `/mcp` path.

## Prerequisites

* **A Pinecone API key** with access to your Nexus project. Create one in the [Pinecone console](https://app.pinecone.io/organizations/-/keys).
* **The MCP endpoint.** Your deployment's workspace host with the `/mcp` path (the base of `nexus_default_workspace_data_console_url` from the [install output](/guides/nexus/byoc/deploy)).
* **Node.js**, so the `mcp-remote` bridge can run through `npx`.

## Connect

Add this server config to your MCP client. Swap `YOUR_PINECONE_API_KEY` for your Pinecone API key. The server logs in with it per request, so every caller queries their own project. For clients that launch local stdio servers, the `mcp-remote` bridge connects them to the remote Streamable HTTP endpoint.

```json theme={null}
{
  "mcpServers": {
    "nexus": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://YOUR_WORKSPACE_HOST/mcp",
        "--header", "X-Pinecone-Api-Key:YOUR_PINECONE_API_KEY",
        "--transport", "http-only"
      ]
    }
  }
}
```

## Tools

* `list_contexts`: list the contexts available to your project (each has a `slug`, and only curated contexts are queryable). Takes no arguments and returns an array of context objects, each shaped `{ slug, name, id, description, queryable, is_curating, is_optimizing, last_curated_at, last_optimized_at }`. `queryable` turns true once the context has been curated, `is_curating` and `is_optimizing` flag whether work is running now, and the two timestamps are ISO strings or `null`.
* `query_context`: submit a question scoped to one context. Args: `context` (slug), `question`. Runs in background mode and returns a `query_id` immediately without waiting for the answer. The return object is `{ query_id, status, model }`. Pass the `query_id` to `get_query` to fetch the result.
* `get_query`: poll the result of a submitted query. Args: `query_id`. Returns `{ query_id, answer, output_json, citations, model, status, error }`. `answer` is the grounded answer text, or `null` until it is ready. `output_json` holds structured output when the query requested a shape, otherwise `null`. `citations` is an array of source references and `error` is set only when the query failed. Keep polling until `status` is `completed`, `failed`, or `cancelled`.


# Pinecone Nexus
Source: https://docs.pinecone.io/guides/nexus/overview

Pinecone Nexus is the knowledge engine for agents. It compiles your data into queryable knowledge once, then serves grounded, cited answers to agents on every call.

You point Nexus at your sources and curate them into a context. Agents then query that context with a single call and get back a structured, grounded answer with citations, instead of re-assembling context from raw chunks on every request.

Traditional RAG hands an agent ranked chunks and leaves it to search, stitch, and re-search. Nexus does that work once, upstream, so agents spend their budget on reasoning instead of re-orienting.

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="/guides/nexus/quickstart">
    Prepare your first context, then query it.
  </Card>

  <Card title="Key concepts" icon="book" href="/guides/nexus/concepts">
    Contexts, manifests, artifacts, sessions, and the Query API.
  </Card>

  <Card title="How Nexus works" icon="lightbulb" href="/guides/nexus/how-it-works">
    Curated artifacts for retrieval, then answers composed over a retrieval SDK.
  </Card>

  <Card title="Bring your own cloud" icon="cloud" href="/guides/nexus/byoc/overview">
    Deploy Nexus in your own cloud account.
  </Card>
</CardGroup>

## What you can do

* **Turn raw sources into queryable knowledge.** Upload documents or connect a data source, then curate them into a searchable context. There is no chunking pipeline or eval set to hand-build.
* **Ask in one call.** Agents issue a KnowQL query (`ask` plus `scope`, optionally a typed `shape`) and get back a grounded, cited answer. One query is a turn. Multi-turn conversations are sessions.
* **Compose across domains.** A single query can span multiple contexts, so knowledge is a graph of contexts rather than one monolithic index.
* **Keep answers grounded and scoped.** Answers carry citations, and access is scoped to your Pinecone project.

## Why Nexus

The most expensive part of an agent is not reasoning. It is knowledge acquisition. Agents built on raw retrieval burn tokens re-orienting on every call and loop through retrieve, evaluate, and re-retrieve cycles. Nexus compiles the knowledge once and serves it on every call:

* **Cheaper than agentic RAG.** The expensive work happens once at curation time, not per query, so agents spend far fewer tokens.
* **Faster than a retrieval loop.** A single query replaces the multi-step retrieve, evaluate, and re-retrieve cycle.
* **Trusted, grounded answers.** Each one carries citations and is scoped to your Pinecone project, running on the Pinecone Database underneath.

## What Nexus is not

* **Not a vector database.** The Pinecone Database sits *underneath* Nexus as the retrieval substrate. Nexus is the engine layer above it.
* **Not RAG.** RAG returns ranked chunks for a human to read. Nexus compiles typed, grounded artifacts purpose-built for agents and returns answers.
* **Not an agent framework.** Nexus is knowledge infrastructure: query in, answer out. Your agent decides what to do with the answer.


# Query tracing
Source: https://docs.pinecone.io/guides/nexus/query-tracing

Trace any query to see the steps, retrieval code, tokens, and cost behind its answer.

Every query is recorded as a trace. The trace explorer shows how Pinecone Nexus reached an answer, from the steps the model ran down to the retrieval code it generated, along with the tokens, time, and cost each step took. Use it to understand a result or debug an unexpected one.

To open a trace, click **Show in trace explorer** after a query returns, or reopen a past query from its session in the **Sessions** list. A trace opens to the query text, the model that answered, and the views below.

## Summary bar

The summary bar reports the shape of the run at a glance.

* **Steps.** How many reasoning steps the model took, plus the final answer.
* **Tool calls.** How many times it called the retrieval SDK.
* **Tokens.** Input and output tokens for the whole query.
* **Latency.** Wall-clock time to produce the answer.
* **Cost.** Total cost, with a breakdown in **Cost detail**.

## Cost detail

**Cost detail** breaks the run down by tokens and cost.

* **Where the tokens went.** How the spend divides between the reasoning steps and the final synthesis, plus the total billed.
* **New input by step.** The fresh input tokens each step adds. Every step re-sends the whole conversation, so only the new tokens are fresh work. The carried remainder is re-read context that can be served from the prompt cache.
* **Output tokens by step.** The output tokens produced by each step and the answer.
* **Caching savings.** How much input was served from cache versus billed as fresh, with an effective cost estimate. Cached input bills far below fresh input, so a run that reuses more context costs less.

## Spans and inspector

The trace lists each span with its duration, from the model's own reasoning steps to the individual tool calls it made. Select any span to update the **inspector** with the detail for that span.

* **A reasoning step** shows its input and output tokens, its timing (split into decide time while the model reasons and execute time while the code runs), its cost, and the generated code the model wrote and ran.
* **A tool call** (for example, `query_db()`) shows its arguments (the query it ran), its result (such as the number of rows returned), and its timing.

This is the same agent loop described in [Queries](/guides/nexus/how-queries-work), made visible one span at a time.

## Final answer

The trace ends with the final answer produced for the query, the same grounded response the caller receives.


# Nexus quickstart
Source: https://docs.pinecone.io/guides/nexus/quickstart

Deploy Pinecone Nexus with bring-your-own-cloud (BYOC), build a context from your own documents, and run your first query from the deployment console.

Pinecone Nexus runs in your own cloud account. This quickstart deploys Nexus with bring-your-own-cloud (BYOC), then builds a context from your own documents and queries it from your deployment's console.

## Prerequisites

* A Pinecone **Enterprise** plan (required for BYOC).
* A dedicated cloud account (AWS, GCP, or Azure) with admin access, plus the install tooling. See the [deploy prerequisites](/guides/nexus/byoc/deploy#prerequisites) for the full list.

## 1. Deploy Nexus

Nexus runs in your own cloud, so deploying it comes first.

<Steps>
  <Step title="Install Nexus">
    Follow [Deploy Nexus BYOC](/guides/nexus/byoc/deploy) to install Nexus in your own cloud account with the Pulumi installer.
  </Step>

  <Step title="Open your deployment's console">
    When the install finishes, it prints your workspace console URL. Open it to reach your deployment's console, where the rest of this quickstart happens.
  </Step>
</Steps>

## 2. Add a context

Build a context from your own documents.

<Steps>
  <Step title="Create a context">
    In your deployment's console sidebar, next to **Contexts**, click **+ New**. On the **New context** tab, enter a **Name** (the URL slug is generated from it) and a **Description**, then click **Create context**.
  </Step>

  <Step title="Import sources">
    On the **Sources** tab, click **+ Import**, then bring in your documents one of these ways:

    * **Upload** files or an archive.
    * Pull from a public **Hugging Face** or **GitHub** repository URL.
    * Connect a **Box** or **Google Drive** account and import from it.
  </Step>

  <Step title="Design the manifest">
    On the **Design** tab, pick a **[manifest](/guides/nexus/context-design) template** that fits your sources (for example, **General knowledge base**). The template describes the artifacts and edges it will build and shows an estimated cost and time.
  </Step>

  <Step title="Curate">
    Apply the template to [curate](/guides/nexus/how-curation-works). Nexus chunks your sources and distills them into the artifacts the manifest defines, then indexes everything. Follow progress on the **Sources** and **Knowledge** tabs, and under **Activity**.
  </Step>
</Steps>

<Tip>
  Have a `.context.zip` pack? In the **New context** dialog, open the **Restore** tab, drop the pack (or click **choose a file**), then click **Restore context**. Packs come from a context's **Packs** tab.
</Tip>

## 3. Query your context

Once curation finishes, ask your context a question and get a grounded, cited answer.

<Steps>
  <Step title="Open the Query tab">
    Open your context's **Query** tab, and optionally pick the answering **model**.
  </Step>

  <Step title="Ask a question">
    Type your question in the **Search this context** box and run it. Nexus returns a grounded, cited answer with suggested follow-up topics, and saves it as a session you can reopen from **Sessions**.
  </Step>
</Steps>

<Tip>
  To query several contexts at once, start a session from **Sessions** with **+ New session**, click each context in the **Query across** row, and ask.
</Tip>

You can also query from your own code, using the [Nexus API](/reference/api/nexus/introduction) or an [MCP server](/guides/nexus/mcp-server).


# 2026 releases
Source: https://docs.pinecone.io/nexus-release-notes/2026

Pinecone Nexus release notes for 2026.

## August 2026

<Update label="2026-08-06">
  ### Nexus launch

  Pinecone Nexus, the knowledge engine for agents, is now generally available. Point Nexus at your sources, curate them into a context, and query that context to get grounded, cited answers. Get started in the [Nexus quickstart](/guides/nexus/quickstart).
</Update>


# Feature availability
Source: https://docs.pinecone.io/nexus-release-notes/feature-availability

Feature availability phases for Pinecone Nexus.

This page defines the different availability phases of a feature in Pinecone.

The availability phases are used to communicate the maturity and stability of a feature. The availability phases are:

* **Early access**: In active development and may change at any time. Intended for user feedback only. In some cases, users must be granted explicit access to the API by Pinecone.

* **Public preview**: Unlikely to change between public preview and general availability. Not recommended for production usage. Available to all users.

* **Limited availability**: Available to select customers in a subset of regions and providers for production usage.

* **General availability**: Will not change on short notice. Recommended for production usage. Officially [supported by Pinecone](/troubleshooting/pinecone-support-slas) for non-production and production usage.

* **Deprecated**: Still supported, but no longer under active development, except for critical security fixes. Existing usage will continue to function, but migration following the upgrade guide is strongly recommended. Will be removed in the future at an announced date.

* **End of life (EOL)**: Removed, and no longer supported or available.

<Note>
  A feature is in **general availability** unless explicitly marked otherwise.
</Note>


# Authentication
Source: https://docs.pinecone.io/reference/api/nexus/authentication

Authenticate to the Nexus API with your Pinecone API key, sent directly or exchanged for a short-lived session token.

All requests to the [Pinecone Nexus API](/reference/api/nexus/introduction) authenticate with a valid [Pinecone API key](/guides/production/security-overview#api-keys) for the target project. The Pinecone project is the tenancy boundary.

## Get an API key

[Create an API key](https://app.pinecone.io/organizations/-/projects/-/keys) in the Pinecone console.

```bash theme={null}
export PINECONE_API_KEY="YOUR_API_KEY"
export NEXUS_BASE_URL="https://YOUR_WORKSPACE_HOST/api"
```

`YOUR_WORKSPACE_HOST` is your deployment's workspace host, from the `nexus_default_workspace_data_console_url` output of the [install](/guides/nexus/byoc/deploy).

## Session token

The primary method. Exchange your API key for a short-lived bearer token with `POST /auth/login`, then send that token as `Authorization: Bearer <token>` on every request.

```bash curl theme={null}
export NEXUS_TOKEN="$(
  curl -fsS "$NEXUS_BASE_URL/auth/login" \
    -H 'Content-Type: application/json' \
    -H 'X-Pinecone-Api-Version: 2026-07' \
    -d "{\"api_key\":\"$PINECONE_API_KEY\"}" \
  | jq -r '.token'
)"

curl -fsS "$NEXUS_BASE_URL/contexts" \
  -H "Authorization: Bearer $NEXUS_TOKEN" \
  -H 'X-Pinecone-Api-Version: 2026-07'
```

## API key

Alternatively, send your Pinecone API key directly in the `X-Pinecone-Api-Key` header, with no login exchange.

```bash curl theme={null}
curl -fsS "$NEXUS_BASE_URL/contexts" \
  -H "X-Pinecone-Api-Key: $PINECONE_API_KEY" \
  -H 'X-Pinecone-Api-Version: 2026-07'
```


# Pinecone Nexus API
Source: https://docs.pinecone.io/reference/api/nexus/introduction

Programmatic access to Nexus: manage contexts and sources, curate, and query with KnowQL.

The Pinecone Nexus API gives you programmatic access to the same operations available in the Nexus console: managing contexts and sources, curating, and querying with KnowQL. Anything you can do in the console you can do through the API.

## Base URL

Your deployment's workspace host, from the `nexus_default_workspace_data_console_url` output of the [install](/guides/nexus/byoc/deploy), with the `/api` path:

```
https://YOUR_WORKSPACE_HOST/api
```

## Versioning

Nexus uses date-based versioning through the `X-Pinecone-Api-Version` header. Send the version you built against, for example `2026-07`. Omit it to use the default version. The older `/api/v0` path stays functional as a legacy alias.


# Pinecone Assistant architecture
Source: https://docs.pinecone.io/reference/architecture/assistant-architecture

Pinecone Assistant architecture overview covering document ingestion, chunking, vector retrieval, and LLM response generation for RAG.

This page describes the architecture for [Pinecone Assistant](/guides/assistant/overview).

## Overview

[Pinecone Assistant](/guides/assistant/overview) runs as a managed service on the Pinecone platform. It uses a combination of machine learning models and information retrieval techniques to provide responses that are informed by your documents. The assistant is designed to be easy to use, requiring minimal setup and no machine learning expertise.

Pinecone Assistant simplifies complex tasks like data chunking, vector search, embedding, and querying while ensuring privacy and security.

<img />

<img />

## Data ingestion

When a [document is uploaded](/guides/assistant/manage-files), the assistant processes the content by chunking it into smaller parts and generating [vector embeddings](https://www.pinecone.io/learn/vector-embeddings-for-developers/) for each chunk. These embeddings are stored in an [index](/guides/index-data/indexing-overview), making them ready for retrieval.

## Data retrieval

During a [chat](/guides/assistant/chat-with-assistant), the assistant processes the message to formulate relevant search queries, which are used to query the index and identify the most relevant chunks from the uploaded content.

## Response generation

After retrieving these chunks, the assistant performs a ranking step to determine which information is most relevant. This [context](/guides/assistant/context-snippets-overview), along with the chat history and [assistant instructions](/guides/assistant/manage-assistants#add-instructions-to-an-assistant), is then used by a large language model (LLM) to generate responses that are informed by your documents.


# Analytics and event logs
Source: https://docs.pinecone.io/guides/marketplace/analytics-and-event-logs

Track end-user activity, refusal rates, feedback, and event logs in a Pinecone Marketplace deployment for analytics, auditing, and debugging.

<Note>
  This feature is in [public preview](/release-notes/feature-availability).
</Note>

Every deployment has a dashboard with analytics and an append-only event log. Use them to understand how end users are using the knowledge application and where it can be improved.

## Analytics

The analytics view shows:

* Active end users over time.
* Conversation and query volume.
* Refusal rate, broken down by `OUT_OF_SCOPE` and `BLOCKED` outcomes.
* Most-asked questions.
* Feedback ratings over time.
* Per-version traffic and quality trends.

Use analytics to spot patterns: a sudden spike in refusals usually means a content gap or a poorly scoped knowledge base; a drop in feedback ratings after a publish usually means a regression.

## Event log

The event log captures every meaningful action for a deployment. Events include:

| Category     | What it covers                                                                                                                                                                 |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Lifecycle    | Deployment created, version building, publish started, publish completed, version active, version failed, rollback.                                                            |
| Chat         | Each query, the routing decision, the Knowledge Agent Toolkit (KAT) outcome (`CALL_KB`, `ASK_SLOT`, `BLOCKED`, `OUT_OF_SCOPE`), the knowledge bases queried, and the response. |
| Feedback     | Thumbs-up and thumbs-down ratings, with optional comments.                                                                                                                     |
| Sync         | Source sync runs, with success or failure and per-file detail.                                                                                                                 |
| Provisioning | Background provisioning steps for each publish.                                                                                                                                |

Events are append-only and timestamped. The dashboard supports filtering and searching by category, version, knowledge base, and outcome.

## Using analytics and events together

A typical investigation looks like this:

1. Notice an increase in refusals in analytics.
2. Filter the event log to recent `OUT_OF_SCOPE` outcomes.
3. Find common patterns in the refused questions.
4. Decide whether to add content, expand scope, or adjust manifests.
5. Edit the deployment, publish a new version, and watch the next round of analytics.

## Exporting and integrations

Analytics and events surface in the deployment dashboard. Programmatic access through the API is also available; see the [Reference](/reference/api/marketplace/events) tab.


# Configure components
Source: https://docs.pinecone.io/guides/marketplace/configure-components

Enable visual components like comparison tables, timelines, and coverage matrices in a Pinecone Marketplace knowledge application interface.

<Note>
  This feature is in [public preview](/release-notes/feature-availability).
</Note>

A component is a visual primitive a knowledge application can render in addition to text. Components let an answer take the most useful shape for the question instead of forcing every response into prose.

Components are read-only and retrieval-oriented. They render information from the connected sources; they do not write back to source systems.

## Available components

| Component         | Use it for                                                               |
| ----------------- | ------------------------------------------------------------------------ |
| Comparison tables | Side-by-side comparisons of products, plans, policies, or options        |
| Content cards     | Browsable summaries of documents, people, or items with links to sources |
| Timelines         | Sequences of dated events, such as case milestones or release histories  |
| Progress trackers | Step-by-step processes such as onboarding checklists                     |
| Coverage matrices | Two-dimensional lookups, such as benefits coverage by plan and region    |
| Geolocation maps  | Locations and venue context                                              |

## Enabling components

From the deployment dashboard, enable the components you want the application to use. Components must be compatible with the [layout](/guides/marketplace/configure-layouts):

* Chat layouts can render any component inline in an answer.
* Search layouts work best with content cards and comparison tables.
* Structured and hybrid layouts work best with comparison tables, coverage matrices, timelines, and progress trackers.

## How the application picks a component

The application chooses a component based on the question, the response shape, and the components you have enabled. If a question is best answered with text, the application returns text even if components are enabled.

## Component output and citations

Every component cites the documents it was built from. End users can click into a cited source to see the original document. See [Citations](/guides/marketplace/end-user/citations).


# Configure layouts
Source: https://docs.pinecone.io/guides/marketplace/configure-layouts

Choose a chat, search, structured, or hybrid consumer layout for a Pinecone Marketplace knowledge application to match your end-user experience.

<Note>
  This feature is in [public preview](/release-notes/feature-availability).
</Note>

A layout is the high-level shape of the consumer interface. Marketplace provides four layouts. Each [template](/guides/marketplace/templates-overview) suggests a default layout, which you can override.

## Chat

A conversational thread with a single input box. Each turn shows the question, the answer with inline citations, and any rendered components. Suggested follow-ups appear after each answer.

Best for:

* Open-ended Q\&A across documents.
* Long-running conversations where context carries between turns.

Templates that recommend chat: Customer Support, HR Benefits, Onboarding and Training, Local Government Citizen Engagement.

## Search

A query box with ranked results, source previews, and an "answer" panel that summarizes the top matches with citations.

Best for:

* Finding a specific clause, document, or passage.
* Domains where the end user wants to scan multiple results before drilling in.

Templates that recommend search: Legal Document Search, Financial Filings Analyzer.

## Structured

Form-style inputs that guide the end user to provide the information needed for a structured answer, such as a comparison table or a coverage matrix.

Best for:

* Repeatable, parameterized tasks such as deal sizing or coverage lookups.
* Workflows where end users want a consistent output shape every time.

Templates that recommend structured: Deal Desk.

## Hybrid

Chat plus a persistent structured panel. The chat handles open-ended questions, and the panel shows visual components such as comparison tables, timelines, or coverage matrices that update as the conversation progresses.

Best for:

* Workflows that mix exploration with reference output.
* Sales, legal, or research tasks where the end user wants both an answer and a working surface.

Templates that recommend hybrid: Sales Enablement, Event Management.

## Switching layouts

You can change a deployment's layout from the dashboard. Switching layouts creates a new building version and may require you to enable or disable specific [components](/guides/marketplace/configure-components). Publish the new version to apply the change.


# Configure operating parameters
Source: https://docs.pinecone.io/guides/marketplace/configure-operating-parameters

Tune the system prompt, starter prompts, and response style of a Pinecone Marketplace knowledge application through operating parameter settings.

<Note>
  This feature is in [public preview](/release-notes/feature-availability).
</Note>

Operating parameters control how a knowledge application responds. They are set initially by the [template](/guides/marketplace/templates-overview) and can be overridden at any time from the deployment dashboard.

## System prompt

The system prompt sets the application's voice, tone, and high-level instructions. Each template ships with a system prompt tuned for its vertical. Use the system prompt to:

* Define the application's persona and tone.
* Constrain what topics the application will engage with.
* Specify formatting preferences, such as bullet lists or short paragraphs.

<Tip>
  Keep the system prompt focused. Use [KAT guardrails](/guides/marketplace/kat-overview#guardrails-and-scope) for hard policy rules and the system prompt for tone and style.
</Tip>

## Starter prompts

Starter prompts are the suggestions end users see in the empty state of the consumer interface. Marketplace generates starter prompts automatically on publish based on the connected sources, and you can edit or replace them.

## Response style

Configure response defaults such as:

* **Length**: short, medium, or long.
* **Citations**: required, preferred, or optional.
* **Refusal behavior**: how the application phrases out-of-scope refusals.

## Suggested follow-ups

Enable suggested follow-ups so that the consumer interface offers next questions after each answer. Suggested follow-ups are generated from the response and the connected sources.

## Routing strategy

Choose how queries are routed across knowledge bases. The available strategies and execution modes (`full`, `disambiguation_only`, `single`, `fan_out`, `llm_classify`) are defined in [Knowledge Agent Toolkit (KAT) overview](/guides/marketplace/kat-overview); for selection guidance, see [Multi-domain routing](/guides/marketplace/multi-domain-routing).

## Apply changes

Edits to operating parameters create a new building version. Publish the version to send the changes to end users. See [Manage versions and rollback](/guides/marketplace/manage-versions-and-rollback).


# Connectors overview
Source: https://docs.pinecone.io/guides/marketplace/connectors-overview

How Pinecone Marketplace connectors ingest documents, keep them in sync with source systems, and let operators add manually uploaded files.

<Note>
  This feature is in [public preview](/release-notes/feature-availability).
</Note>

A connector is the integration that ingests documents from a source system into a knowledge base. Marketplace handles the ingestion pipeline, normalizes content, and keeps the knowledge base in sync as the source changes. You can also upload files directly when a source connector is not the right fit.

## Available connectors

| Connector     | Type               |
| ------------- | ------------------ |
| Google Drive  | OAuth              |
| Manual upload | Direct file upload |

If you need a connector that is not listed, contact your Pinecone account team or [Pinecone support](https://app.pinecone.io/organizations/-/settings/support).

## How a connector works

When you connect a source to a knowledge base:

1. You authenticate to the source through OAuth or upload files directly.
2. You select the folders, files, or scope the connector should ingest.
3. Marketplace mirrors the selected content, processes each file, and indexes it through Pinecone Assistant.
4. Periodic sync runs detect changes and update the knowledge base.

OAuth secrets are encrypted at rest. Sync runs report status to the deployment dashboard.

## Connector capabilities

Connectors are described by a common adapter contract that covers:

* **Authentication**: how the connector signs in to the source.
* **Selection**: how the operator picks the scope to ingest, such as a folder picker.
* **Sync**: how often the connector polls and how it detects changes.
* **Normalization**: how content is converted to the format Pinecone indexes.
* **Health**: how the connector reports failures or stalled syncs.

## Connect Google Drive

Google Drive is the primary connector for ingesting documents into a deployment.

### Before you begin

* A deployment with at least one knowledge base. See [Create a deployment](/guides/marketplace/create-a-deployment).
* A Google account with access to the folder you want to use.
* Permission from the document owner to ingest the folder if it is shared with you.

### Steps

1. **Open the knowledge base.** In the deployment dashboard, open the knowledge base you want to connect Google Drive to. Select **Add source** and choose **Google Drive**.
2. **Authorize Google Drive.** Sign in with the Google account that has access to the folder. Marketplace requests read-only access to the files you select.
3. **Select files and folders.** Use the Google Picker to select a single folder (recursive ingest of supported file types), a subset of files within a folder, or multiple folders. Selections are scoped to the knowledge base; other knowledge bases in the same deployment have their own selections.
4. **Confirm the sync.** Marketplace runs an initial sync, mirrors the selected files, processes each one, and indexes the content. The dashboard shows progress per file.
5. **Periodic sync runs automatically.** Once the initial sync finishes, Marketplace polls Google Drive on a schedule and re-ingests files that have changed. New files added to a selected folder are picked up on the next sync run.

### Permissions and visibility

Marketplace ingests only the files you select. Documents are scoped to the knowledge base. End users of the knowledge application see content from the knowledge base when they ask questions; they do not get direct access to the underlying Google Drive files.

### Troubleshooting

| Symptom               | What to check                                                                                             |
| --------------------- | --------------------------------------------------------------------------------------------------------- |
| Sync fails to start   | The Google account still has access to the selected folders.                                              |
| Files are missing     | The file type is supported by Pinecone Assistant. See [Files overview](/guides/assistant/files-overview). |
| Stale answers         | Check sync status on the dashboard; you can trigger a manual sync.                                        |
| Authentication errors | The Google OAuth grant has not been revoked. Reconnect the source if needed.                              |

## Manual uploads

You can upload files directly to a knowledge base instead of connecting them through a source connector. Manual uploads are useful for one-off documents, small document sets, or content that is not in a supported source system.

### Before you begin

* A deployment with at least one knowledge base. See [Create a deployment](/guides/marketplace/create-a-deployment).
* Files in a format supported by Pinecone Assistant. See [Files overview](/guides/assistant/files-overview).

### Upload files

1. Open the knowledge base in the deployment dashboard.
2. Select **Add source** and choose **Manual upload**.
3. Drag and drop files into the upload area, or browse to select them.
4. Marketplace validates each file, stages it, and queues it for ingestion.

### Updating uploaded files

To update a manually uploaded file, upload the new version with the same name. Marketplace replaces the previous file. To remove a file, delete it from the knowledge base.

<Note>
  Manually uploaded files do not sync from a source. If you want changes in a source to flow through automatically, use a connector instead.
</Note>

## Mixing connectors and uploads

A knowledge base can combine connector-synced content with manually uploaded files. Use connectors for content you want to stay in sync, and manual uploads for one-off documents.

## Sync and freshness

For each connected source, Marketplace stores the operator's selection, polls the source on a schedule, detects new, updated, and deleted files, and re-ingests the knowledge base incrementally. Manually uploaded files do not sync; replace them by uploading a new version.

### Sync status

The deployment dashboard shows sync status per source and per file:

* **Synced**: the file is up to date with the source.
* **Syncing**: the file is being processed.
* **Failed**: ingestion failed. The error is shown next to the file.
* **Removed**: the file was deleted from the source and removed from the knowledge base.

### Trigger a manual sync

To force an immediate sync, open the source in the deployment dashboard and select **Sync now**. Manual syncs do not change the periodic schedule.

### Freshness across versions

When you publish a new version of a deployment, Marketplace re-runs introspection and starter generation against the latest content. End users always interact with the active version. If a sync change introduces unexpected behavior, you can roll back to a previous version. See [Manage versions and rollback](/guides/marketplace/manage-versions-and-rollback).

### Limits

Sync frequency and connector behavior are governed by the underlying connector adapter.


# Consumer authentication
Source: https://docs.pinecone.io/guides/marketplace/consumer-auth-overview

Configure consumer sign-in for a Pinecone Marketplace deployment using link access or Google sign-in to control who can use your knowledge application.

<Note>
  This feature is in [public preview](/release-notes/feature-availability).
</Note>

Consumer authentication controls who can use a published knowledge application. Each deployment configures its own consumer authentication independently.

## Available providers

| Provider                          | Use it for                                                                                |
| --------------------------------- | ----------------------------------------------------------------------------------------- |
| [Link access](#link-access)       | Internal pilots, demos, or applications you intend to share with anyone who has the link. |
| [Google sign-in](#google-sign-in) | Applications used by people in a Google-based organization.                               |

## How to choose

* Pick **link access** when you need the lowest-friction option and the application does not require identifying who asked what.
* Pick **Google sign-in** when you want interactions tied to a Google account.

You can change the consumer authentication provider from the deployment dashboard. Changing the provider creates a new building version; publish the version to apply the change.

## Link access

Link access is the lowest-friction consumer authentication option. Anyone who has the deployment URL can use the knowledge application without signing in. Use it for internal pilots, demos, and applications where you do not need to identify who is asking questions.

### Configure link access

1. Open the deployment dashboard.
2. Go to **Access**.
3. Set the consumer authentication provider to **Link**.
4. Save the change. Marketplace creates a new building version.
5. Publish the version. See [Publish a deployment](/guides/marketplace/publish-a-deployment).

### Share the URL

Once a deployment is published, copy its URL from the dashboard and send it to end users. End users open the URL and start using the application immediately.

### What link access does and does not do

| Does                                         | Does not do                      |
| -------------------------------------------- | -------------------------------- |
| Let anyone with the link use the application | Identify individual end users    |
| Log events for every interaction             | Tie events to a user identity    |
| Apply the deployment's scope and guardrails  | Provide row-level access control |

If you need to know who asked what, use [Google sign-in](#google-sign-in) instead.

## Google sign-in

Google sign-in requires end users to authenticate with Google before using the knowledge application. Use it when you want every interaction tied to a verified Google account.

### Configure Google sign-in

1. Open the deployment dashboard.
2. Go to **Access**.
3. Under **Access**, select the Google sign-in option.
4. Configure the allowed sign-in scope: restrict to one or more email domains, or allow any Google account.
5. Save the change. Marketplace creates a new building version.
6. Publish the version.

### Sign-in flow

When end users open the deployment URL, they are prompted to sign in with Google. Marketplace checks the email against the allowed scope. Authorized users land in the application; unauthorized users see a friendly access-denied page. Sessions persist until the end user signs out.

### Revoking access

To revoke an end user's access, update the allowed sign-in scope to exclude their email or domain, then publish the change. Existing sessions for excluded users will fail on next request.

## Sessions and identity

When end users sign in:

* Their session is scoped to the deployment.
* Their identity is recorded in the [event log](/guides/marketplace/analytics-and-event-logs) for traceability.
* Their feedback is associated with their identity.

Link access does not establish an end-user identity. Events from link-accessed applications are still logged, without the user attribution.

## Sharing the application

After publishing, copy the deployment URL from the dashboard and share it with end users. The URL is the entry point regardless of which consumer authentication provider is configured.


# Create a deployment
Source: https://docs.pinecone.io/guides/marketplace/create-a-deployment

Create a new Pinecone Marketplace deployment from a vertical template, name it, choose a layout, and configure operating parameters for your use case.

<Note>
  This feature is in [public preview](/release-notes/feature-availability).
</Note>

This page shows you how to create a [deployment](/guides/marketplace/concepts#deployment) in Pinecone Marketplace.

## Before you begin

* A Marketplace account. See the [Quickstart](/guides/marketplace/quickstart) for access.
* A clear use case in mind, so you can pick a starting [template](/guides/marketplace/template-catalog).

## 1. Open the catalog

Go to [marketplace.pinecone.io](https://marketplace.pinecone.io) and select **New deployment**. The catalog lists the available vertical templates.

## 2. Pick a template

Choose the template that most closely matches your use case. Templates set the initial system prompt, recommended layout, suggested components, and starter prompts. You can change any of these later.

## 3. Name the deployment

In the setup wizard:

* Give the deployment a short, descriptive name.
* Add a one-line description that end users see in the application header.
* Select the Pinecone organization and project the deployment belongs to.

## 4. Choose a layout

Pick the consumer layout that fits the experience you want: chat, search, structured, or hybrid. The template suggests a default, which you can override. See [Configure layouts](/guides/marketplace/configure-layouts).

## 5. Configure operating parameters

Tune the system prompt, response style, and other operating parameters. For details, see [Configure operating parameters](/guides/marketplace/configure-operating-parameters).

## 6. Add a knowledge base

A deployment must have at least one knowledge base. For each knowledge base:

* Give it a name that describes the domain (for example, `policies`, `product-docs`).
* Connect a source. See [Connectors](/guides/marketplace/connectors-overview).

You can add additional knowledge bases now or later. Multi-knowledge-base deployments use the [Knowledge Agent Toolkit (KAT)](/guides/marketplace/kat-overview) to route between domains.

## 7. Save as a building version

When you finish the wizard, Marketplace saves your work as a building version. The deployment is not yet live. From the dashboard, you can:

* Continue editing the building version.
* Publish it. See [Publish a deployment](/guides/marketplace/publish-a-deployment).

<Note>
  You can edit a building version as many times as you want before publishing. Each edit replaces the in-progress configuration; nothing is sent to end users until you publish.
</Note>


# Deployer authentication
Source: https://docs.pinecone.io/guides/marketplace/deployer-auth

Sign in to Pinecone Marketplace as an operator to create deployments, manage sessions across devices, and audit deployer actions in the event log.

<Note>
  This feature is in [public preview](/release-notes/feature-availability).
</Note>

Deployer authentication controls who can sign in to Marketplace, create deployments, edit configuration, and publish versions. This is separate from [consumer authentication](/guides/marketplace/consumer-auth-overview), which controls who can use a published knowledge application.

## Sign in or sign up

Operators sign in to Marketplace at [marketplace.pinecone.io](https://marketplace.pinecone.io). The Marketplace homepage offers `Sign up free` and `Log in` from the header. Sign-in is linked to your Pinecone organization and project, so apps and assistants you create are scoped correctly.

Operators with an existing Pinecone account can also reach Marketplace through the **Marketplace ↗** entry in the Pinecone console sidebar.

## Sessions

Sessions are stored on Marketplace's backend. Signing out ends the active session. Operators can sign in from multiple devices.

## Roles

Every deployment is owned by the operator who created it. Org and team membership with role-based access (admin, editor, viewer) is not supported.

## Audit

Significant operator actions are recorded in the deployment event log. See [Analytics and event logs](/guides/marketplace/analytics-and-event-logs).


# Ask questions
Source: https://docs.pinecone.io/guides/marketplace/end-user/ask-questions

Tips for end users on asking clear, specific questions in a Pinecone Marketplace knowledge application, using follow-ups, and handling clarifications.

<Note>
  This feature is in [public preview](/release-notes/feature-availability).
</Note>

A knowledge application answers questions in plain language, grounded in the documents an operator has connected. The way you ask affects how useful the answer is.

## How to ask

* **Be specific.** "What is the parental leave policy in California?" beats "tell me about leave."
* **Include the context that matters.** Region, plan, role, product line, and dates often change the answer.
* **Use follow-ups.** Once you get an answer, ask the next question naturally; the application carries context across turns.

## Suggested follow-ups

After each answer, the application may suggest related questions. Use them to drill down without retyping context.

## When the application asks you a question back

If a question is ambiguous or missing context, the application asks you to clarify. Pick the option you meant or provide the missing detail. The application uses your clarification for the rest of the conversation.

## When the application says it does not know

A knowledge application is built to be honest about its scope. Common refusals:

* **Out of scope**: the application does not have content that addresses your question. The refusal will list what the application can help with.
* **Blocked**: the application has been configured not to engage with the request.

If you think the application should be able to answer but is refusing, share that feedback with the operator. See [Give feedback](/guides/marketplace/end-user/citations#give-feedback).

## What about completely new conversations?

Starting a new conversation resets context. Use a new conversation when you are switching topics so the application does not carry over slot values from a different question.


# Understand answers
Source: https://docs.pinecone.io/guides/marketplace/end-user/citations

Read citations, work with visual components, export and share answers, and give feedback in a Pinecone Marketplace knowledge application.

<Note>
  This feature is in [public preview](/release-notes/feature-availability).
</Note>

Every answer in a Pinecone Marketplace knowledge application is grounded in connected documents and includes citations. This page covers how to read citations, what visual components mean, how to export and share answers, and how to give feedback that helps the operator improve the application.

## Citations and sources

Citations let you verify an answer and read the original context.

### How citations look

Citations appear inline with the answer, usually as numbered references that link to specific source documents. The sources panel lists the cited documents in order.

### Opening a source

Click a citation or a source in the panel to open the document viewer. The viewer shows the full document scrolled to the cited section where possible, the document's title and metadata, and links to the original source if the operator has enabled them.

### When an answer has no citations

A knowledge application is built to ground every answer. If you see an answer without citations, that usually means the response was a meta-statement (such as a refusal or a clarifying question) rather than content from a document.

If you see what looks like a substantive answer with no citations, share that with the operator. See [Give feedback](#give-feedback).

### Trusting an answer

Citations are how you verify trust. A useful habit:

* For high-stakes questions, open at least one cited source.
* Confirm the source actually says what the answer claims.
* If the source contradicts the answer, give negative feedback so the operator can investigate.

## Visual components

Some answers are easier to read as a table, a timeline, or a map than as plain text. A knowledge application can render the following visual components when an answer fits a structured shape.

| Component         | When you see it                                              |
| ----------------- | ------------------------------------------------------------ |
| Comparison tables | Side-by-side comparisons of options, plans, or policies      |
| Content cards     | Browsable summaries of documents or items                    |
| Timelines         | Sequences of dated events                                    |
| Progress trackers | Step-by-step processes                                       |
| Coverage matrices | Two-dimensional lookups, such as benefits by plan and region |
| Geolocation maps  | Locations and venue context                                  |

### Interacting with components

* Most components are read-only views. Click rows, cards, or items to drill into the underlying source documents.
* Components include citations the same way text answers do.
* If a component does not fit on your screen, it will scroll horizontally where appropriate.

### Why an answer is sometimes a table and sometimes prose

The application picks the shape based on the question, the answer, and the components the operator has enabled. If the operator has not enabled tables, you will get prose even for a comparison question. If you would prefer a different shape for a recurring kind of question, [give feedback](#give-feedback).

## Export and share

You can save and share individual answers or whole conversations.

### Export to PDF

To save an answer or conversation as a PDF, open the answer or conversation, use the export action in the conversation header, choose **PDF**, and save the file. PDF exports include the questions, answers, citations, and any rendered components.

### Share to Slack

If the operator has enabled the Slack share action, open the answer, use the share action, pick a Slack channel or person, and optionally add a note. The shared message includes a summary, citations, and a link back to the answer in the application.

### Linking back to a conversation

The conversation URL is shareable with anyone who has access to the application. Sharing the URL takes the recipient to the same conversation when they open it.

### Privacy

When you share or export an answer, you are sharing the content as it appeared to you. The recipient still needs access to the application to follow citations or continue the conversation.

## Give feedback

Feedback is the most direct way to help the operator improve a knowledge application. Operators can see ratings and comments per answer.

### How to give feedback

After each answer, you can:

* Give a thumbs-up or thumbs-down rating.
* Add an optional comment explaining what was good or what was wrong.

Feedback is associated with the conversation and the version of the application you used.

### When to give feedback

* The answer is wrong or missing context: thumbs down with a comment.
* The application refused a question you think it should be able to answer: thumbs down with a comment that includes the question.
* The answer was exactly what you needed: thumbs up.
* The answer was useful but the format could be better (for example, a table would have been clearer): thumbs up with a comment.

### What happens with your feedback

Feedback shows up in the operator's analytics dashboard and event log. Operators use the patterns to add or rework content in connected sources, tighten or loosen scope and guardrails, adjust operating parameters, or decide whether to roll back a recent publish.

If the operator publishes a new version that addresses your feedback, ask the same question again. The application updates as it improves.


# End user guide
Source: https://docs.pinecone.io/guides/marketplace/end-user/overview

End-user overview of Pinecone Marketplace knowledge applications, including how to sign in with link access or Google and read grounded citations.

<Note>
  This feature is in [public preview](/release-notes/feature-availability).
</Note>

This guide is for people using a knowledge application built with Pinecone Marketplace. If you are building or operating a knowledge application, see the [operator guides](/guides/marketplace/overview) instead.

## What a knowledge application is

A knowledge application is a tool that answers questions about a specific set of documents. It might be your company's HR benefits, your team's product documentation, a legal contract repository, or any other body of knowledge an operator has connected.

Every answer is grounded in the connected documents and includes citations. The application tells you when it does not know something instead of making up an answer.

## Sign in

How you sign in depends on how the operator has configured the application.

### Link access

Some applications are open to anyone who has the URL. Open the URL and you can start asking questions immediately. You will not see a sign-in prompt.

### Sign in with Google

If the application uses Google sign-in:

1. Open the application URL.
2. Select **Sign in with Google**.
3. Choose your Google account.
4. If your email is in the allowed scope, you land in the application.

If you see an access-denied page, contact the operator to confirm whether your account is authorized.

### Signing out

Use the account menu in the application header to sign out. Closing the browser tab also ends the session in most cases.

### Trouble signing in?

* Make sure you are using the URL the operator gave you.
* Confirm you are signed in with the right Google account.
* If your access changed recently, sign out and sign back in.
* If problems persist, contact the operator who shared the application.

## What you can do next

* [Ask questions](/guides/marketplace/end-user/ask-questions) and get grounded answers.
* [Understand answers](/guides/marketplace/end-user/citations): read citations, work with visual components, export, and give feedback.


# Evaluations
Source: https://docs.pinecone.io/guides/marketplace/evaluations

How Pinecone Marketplace runs automatic evaluations on every publish, scoring faithfulness and relevance to catch regressions in a new version.

<Note>
  This feature is in [public preview](/release-notes/feature-availability).
</Note>

Marketplace runs an automatic evaluation on every publish. Evaluations let you see whether a new version improved or regressed quality before opening it up to all end users.

## What an evaluation does

When a deployment publishes, Marketplace:

1. Generates a set of test questions from the connected sources.
2. Asks the new version to answer each test question.
3. Scores each response on faithfulness and relevance using an LLM judge.
4. Records the aggregate result in the version history.

Evaluations run as the final step of publishing. The version becomes active even if the evaluation flags regressions; treat the score as a signal, not a gate.

## Metrics

| Metric       | What it measures                                     |
| ------------ | ---------------------------------------------------- |
| Faithfulness | Whether the answer is grounded in the cited sources. |
| Relevance    | Whether the answer addresses the question.           |

You can drill into per-question results to see which test cases regressed and what the application returned.

## Test question generation

Test questions are generated automatically from the connected content; they are not curated by hand. To get more representative tests, keep the connected sources focused on the domain the application serves.

## Comparing versions

The deployment dashboard shows evaluation results per version. Use the comparison view to see:

* Aggregate score deltas between versions.
* Per-question pass and fail changes.
* Sources cited per response.

If a publish regresses, roll back from the version history. See [Manage versions and rollback](/guides/marketplace/manage-versions-and-rollback).

## End-user feedback

Evaluations measure the application against generated test cases. End-user feedback measures it against real questions. Use both together. See [Analytics and event logs](/guides/marketplace/analytics-and-event-logs).


# Knowledge Agent Toolkit (KAT) overview
Source: https://docs.pinecone.io/guides/marketplace/kat-overview

How the Knowledge Agent Toolkit (KAT) orchestrates multi-domain Pinecone Marketplace apps with manifests, disambiguation, slot filling, and guardrails.

<Note>
  This feature is in [public preview](/release-notes/feature-availability).
</Note>

The Knowledge Agent Toolkit (KAT) is the orchestration layer in Pinecone Marketplace. KAT turns one or more knowledge bases into a coherent multi-domain knowledge application by handling intent extraction, slot filling, multi-domain routing, disambiguation, and guardrails.

KAT is required for any deployment with more than one knowledge base. Single-knowledge-base deployments can use simpler routing strategies.

## What KAT does

For every end-user query, KAT:

1. **Extracts intent**: identifies what the end user is trying to accomplish.
2. **Fills slots**: identifies missing context, such as a region or a product line, and asks the end user for it when needed.
3. **Routes**: picks the right knowledge bases to query based on auto-generated [manifests](#manifests).
4. **Applies guardrails**: blocks queries that violate policy and refuses out-of-scope queries.
5. **Synthesizes a response** (in `full` mode) or hands off to Pinecone Assistant for synthesis (in `disambiguation_only` mode).

## Outcomes

Every KAT decision resolves to one of four outcomes:

| Outcome        | What it means                                                                                                                   |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `CALL_KB`      | Route the query to one or more specific knowledge bases.                                                                        |
| `ASK_SLOT`     | Ask the end user for missing context before answering. See [Disambiguation and slot filling](#disambiguation-and-slot-filling). |
| `BLOCKED`      | Refuse the query because it violates a guardrail. See [Guardrails and scope](#guardrails-and-scope).                            |
| `OUT_OF_SCOPE` | Refuse the query and list what the application can help with instead. See [Guardrails and scope](#guardrails-and-scope).        |

## Execution modes

KAT supports two execution modes:

* **`full`**: KAT runs the complete pipeline, including disambiguation, slot filling, knowledge-base selection, and answer synthesis. Best for multi-domain deployments where consistent orchestration matters.
* **`disambiguation_only`**: KAT routes and disambiguates, then delegates synthesis to Pinecone Assistant. Best when you want KAT's routing intelligence with Pinecone Assistant's response style.

## Strategies for single-knowledge-base deployments

If a deployment has only one knowledge base, you can choose a simpler strategy instead of `full` KAT:

| Strategy       | Behavior                                                           |
| -------------- | ------------------------------------------------------------------ |
| `single`       | Route every query to the only knowledge base.                      |
| `fan_out`      | Query every knowledge base in parallel and merge results.          |
| `llm_classify` | An LLM classifies the query and picks the relevant knowledge base. |

You can change the strategy from the deployment dashboard. See [Configure operating parameters](/guides/marketplace/configure-operating-parameters). For selection guidance across all strategies, see [Multi-domain routing](/guides/marketplace/multi-domain-routing).

## Manifests

A manifest is an automatically generated description of what a knowledge base can answer, what is in scope, and what is out of scope. Manifests are central to how KAT routes queries, disambiguates, and refuses out-of-scope questions.

### Why manifests exist

Without a manifest, KAT would have to retrieve from every knowledge base on every query to discover whether it can answer. With manifests, KAT can pick the right knowledge base before retrieving, refuse out-of-scope questions cleanly instead of producing low-confidence answers, and ask for missing slots only when they would change the answer.

### How a manifest is built

Manifests are built through **progressive introspection**. After publish, Marketplace probes each knowledge base with sampled questions and uses the responses to construct the manifest. Introspection covers the high-level topics the knowledge base can answer, the kinds of questions that are clearly in or out of scope, required slots that change the answer, and suggested starter prompts for the consumer interface.

Introspection runs on initial publish, on republish after major content changes, and when you trigger a manual rebuild from the deployment dashboard.

### Reviewing a manifest

The deployment dashboard shows each knowledge base's current manifest. You can see what KAT considers in scope and out of scope, the slots KAT will ask about, and the starter prompts generated from the content.

Manifests are generated automatically; you do not author them by hand. If a manifest does not match expectations, the right move is usually to adjust the knowledge base content, names, or descriptions and republish.

### Manifests and routing accuracy

Routing quality depends on manifest quality. Two practical guidelines:

* Keep knowledge bases focused. Broad, sprawling knowledge bases produce vague manifests and weaker routing.
* Re-run introspection after large content changes so the manifest stays in sync with reality.

## Disambiguation and slot filling

KAT is built around the assumption that not every question can be answered from the question alone. When information is missing or the question maps to more than one domain, KAT either asks the end user for clarification or routes intelligently based on prior turns.

### Disambiguation

When a question could be answered by multiple knowledge bases, or when an answer would change depending on missing context, KAT pauses to clarify. Disambiguation can take two forms:

* **Domain disambiguation**: KAT asks the end user which knowledge domain they meant.
* **Slot disambiguation**: KAT asks the end user for a specific value, such as a region or a product line.

In both cases, the consumer interface renders the prompt as a clarifying question. Once the end user responds, KAT proceeds with the original query plus the new context.

### Slots

A slot is a named piece of context KAT needs to answer correctly. Common examples include region or location, plan tier or product line, effective date, and user role or persona. Slots can be:

* **Required**: KAT will not answer without the value. Missing required slots produce `ASK_SLOT`.
* **Optional**: KAT will use the slot if available and proceed without it otherwise.

The connected templates and configuration determine which slots are defined. You can review and adjust slots from the deployment dashboard.

### AgentContext and multi-turn behavior

KAT tracks slots and selected knowledge bases across turns through `AgentContext`. End users do not have to repeat themselves; once a value is set in the conversation, KAT carries it forward. `AgentContext` is per-conversation, so starting a new conversation resets context.

KAT only asks for clarification when it would meaningfully change the answer. If two knowledge bases return the same content, or if the missing slot does not affect routing, KAT proceeds without asking.

### Tuning disambiguation

If end users see too many clarifying questions, tighten manifests so domains have less overlap, reduce the number of required slots in the deployment configuration, or improve knowledge base names and descriptions so KAT picks correctly without asking.

If end users see too few clarifying questions and answers are inconsistent, add required slots for context that meaningfully changes the answer, or split an overly broad knowledge base into focused domains.

## Guardrails and scope

A knowledge application should be honest about what it can and cannot answer. KAT enforces two kinds of refusal: **out-of-scope** and **blocked**.

### Out-of-scope refusals

A query is out of scope when no knowledge base in the deployment has the information to answer it. KAT returns `OUT_OF_SCOPE` and the consumer interface shows a refusal that lists what the application can help with instead.

Examples of out-of-scope behavior:

* An HR Benefits application is asked about a competitor's product features.
* A Customer Support application for one product is asked about a different product line.
* A Legal Document Search application is asked for general legal advice.

Out-of-scope refusals are derived from the [manifests](#manifests) KAT builds for each knowledge base. Improving manifests usually improves out-of-scope accuracy.

### Blocked queries

A query is blocked when it violates a guardrail. KAT returns `BLOCKED` and the consumer interface shows a refusal explaining that the request cannot be processed.

Guardrails include refusing to produce content that violates the application's defined scope, refusing to surface content that has been excluded from the knowledge base by the operator, and refusing to return content for which the end user lacks authorization.

You configure scope and exclusion rules from the deployment dashboard.

### Citations and grounding

Every answer is grounded in retrieved content and includes citations. If KAT cannot ground an answer, it refuses rather than producing unsupported content. This is the most important guardrail in the system. For end-user-facing detail on how citations work, see [Understand answers](/guides/marketplace/end-user/citations).

### Tuning the balance

If the application refuses too often, add or expand knowledge bases to cover the missing topics, re-run introspection so manifests reflect new content, or loosen scope rules where appropriate.

If the application answers things it should not, tighten scope rules, split overly broad knowledge bases into focused domains, or add explicit exclusion rules for topics the application must not discuss.

### Observability

Every refusal is logged with the outcome (`BLOCKED` or `OUT_OF_SCOPE`) and the originating query. Use the deployment dashboard to identify questions that should be answered but are being refused, and the other way around. See [Analytics and event logs](/guides/marketplace/analytics-and-event-logs).


# Manage versions and rollback
Source: https://docs.pinecone.io/guides/marketplace/manage-versions-and-rollback

Use versioned publishing in Pinecone Marketplace to stage edits, compare active and building versions, and roll back a deployment when needed.

<Note>
  This feature is in [public preview](/release-notes/feature-availability).
</Note>

Marketplace treats every change to an active deployment as a new version. This makes it safe to iterate on operating parameters, content, and configuration without disrupting end users.

## Versions

A deployment has up to one active version and zero or more building versions:

* **Active version**: what end users see right now.
* **Building version**: an in-progress edit that is not yet live.

When you edit an active deployment, Marketplace creates a building version automatically. You can keep editing without publishing; nothing is sent to end users until you publish the building version. See [Publish a deployment](/guides/marketplace/publish-a-deployment).

## Version history

Every published version is preserved in the deployment's version history. The history includes:

* The version number and publish timestamp.
* The operator who published it.
* A summary of changes from the previous version.
* The evaluation result for that version.

## Rollback

If a new version regresses, you can roll back to a previous version from the version history. Rollback:

1. Promotes the selected previous version to active.
2. Returns end users to the prior behavior on their next interaction.
3. Preserves the regressed version in history so you can inspect what changed.

Rollback is fast because the previous version's underlying assistants and indexes are still provisioned.

## Best practices

* Make small changes between publishes so that evaluations and end-user feedback give you a clear signal.
* Review the evaluation result before promoting a publish to wider end-user traffic.
* Keep notes on each publish so the version history stays meaningful.
* Use rollback freely. The cost of rolling back is low; the cost of leaving a regression in front of end users is higher.

## Limits

All published versions are retained for rollback. There is no manual cleanup or version-count limit.


# Multi-domain routing
Source: https://docs.pinecone.io/guides/marketplace/multi-domain-routing

How the Knowledge Agent Toolkit (KAT) routes queries across multiple knowledge bases in a Pinecone Marketplace deployment for multi-domain answers.

<Note>
  This feature is in [public preview](/release-notes/feature-availability).
</Note>

A multi-domain deployment has more than one knowledge base. Each knowledge base represents a domain, such as HR policies, product documentation, or contracts. The Knowledge Agent Toolkit (KAT) routes every query to the right knowledge bases at runtime so the end user gets a single coherent answer.

For an introduction, see [KAT overview](/guides/marketplace/kat-overview).

## How routing decisions are made

When an end user asks a question, KAT:

1. Extracts intent and any slot values from the query.
2. Looks up each knowledge base's [manifest](/guides/marketplace/kat-overview#manifests) to determine which domains can answer.
3. Picks one or more knowledge bases to query based on relevance and required slots.
4. Issues retrieval calls in parallel.
5. Synthesizes a single answer from the results, with citations.

If no knowledge base can answer the question, KAT returns `OUT_OF_SCOPE`. If a needed slot is missing, KAT returns `ASK_SLOT`.

## Designing knowledge bases for routing

Routing works best when knowledge bases have non-overlapping scope. Some practical guidance:

* Group documents by domain, not by source. A single knowledge base can mix sources from one domain; a single source can be split across knowledge bases if needed.
* Give each knowledge base a name and description that reflects its scope.
* Re-run introspection after major content changes so the manifest stays accurate.

## When to use which strategy

For what each strategy does, see [KAT overview](/guides/marketplace/kat-overview#execution-modes). The table below is selection guidance.

| Strategy                  | Use it when                                                                                |
| ------------------------- | ------------------------------------------------------------------------------------------ |
| `full` KAT                | You have multiple domains and want disambiguation, slot filling, and consistent synthesis. |
| `disambiguation_only` KAT | You want KAT's routing but want Pinecone Assistant to handle synthesis.                    |
| `single`                  | You have one knowledge base and want minimal overhead.                                     |
| `fan_out`                 | Domains overlap and you want every knowledge base to weigh in on every query.              |
| `llm_classify`            | You want lightweight classification without the full KAT pipeline.                         |

## Mixing knowledge bases of different sizes

Knowledge bases do not need to be the same size. KAT uses manifests, not document counts, to make routing decisions. A small knowledge base with a focused scope routes just as cleanly as a large one with broad coverage.

## Observability

The deployment dashboard logs every routing decision with the outcome (`CALL_KB`, `ASK_SLOT`, `BLOCKED`, or `OUT_OF_SCOPE`) and the knowledge bases queried. Use this to identify questions that consistently land on the wrong knowledge base or get refused unexpectedly. See [Analytics and event logs](/guides/marketplace/analytics-and-event-logs).


# Publish a deployment
Source: https://docs.pinecone.io/guides/marketplace/publish-a-deployment

Publish a Pinecone Marketplace deployment to promote a building version to active, run introspection, generate starter prompts, and evaluate quality.

<Note>
  This feature is in [public preview](/release-notes/feature-availability).
</Note>

Publishing promotes a building version of a deployment to active. End users interact with the active version. Publishing is non-blocking: provisioning runs in the background, and you can navigate away and return when the deployment is ready.

## What happens on publish

When you publish a building version, Marketplace:

1. Returns immediately and starts provisioning in the background.
2. Creates or updates the underlying Pinecone assistants for each knowledge base.
3. Uploads any staged files and waits for processing to complete.
4. Runs introspection to build [manifests](/guides/marketplace/kat-overview#manifests).
5. Generates suggested starter prompts for the consumer interface.
6. Runs an automatic [evaluation](/guides/marketplace/evaluations) on a sample of generated questions.
7. Marks the version active when all steps succeed, or marks it failed and surfaces the error.

The previous active version remains live until the new version is fully ready.

## Before you publish

* Confirm the connected sources are in sync. See [Sync and freshness](/guides/marketplace/connectors-overview#sync-and-freshness).
* Review operating parameters and starter prompts. See [Configure operating parameters](/guides/marketplace/configure-operating-parameters).
* Confirm the consumer authentication policy. See [Consumer authentication overview](/guides/marketplace/consumer-auth-overview).

## Publish

From the deployment dashboard, open the building version and select **Publish**. Marketplace shows the version transitioning through provisioning steps in the dashboard.

## Monitor publish progress

The dashboard reports per-step status:

* **Provisioning**: assistants are being created or updated.
* **Processing files**: staged files are being indexed.
* **Introspecting**: manifests are being generated.
* **Generating starters**: starter prompts are being created.
* **Evaluating**: the automatic evaluation is running.
* **Active**: the version is live.
* **Failed**: a step failed; the error is shown.

If publish fails, fix the underlying issue and republish. The previous active version remains untouched.

## After publish

* Share the deployment URL with end users.
* Watch the [event log](/guides/marketplace/analytics-and-event-logs) for early traffic and refusals.
* Review the [evaluation](/guides/marketplace/evaluations) results.
* Iterate on operating parameters or content and publish a new version when needed.

## Publishing again

Editing an active deployment creates a new building version automatically. Publish the building version when you are ready. Each publish is preserved in the version history; see [Manage versions and rollback](/guides/marketplace/manage-versions-and-rollback).


# Authentication
Source: https://docs.pinecone.io/reference/api/marketplace/authentication

Authenticate to the Pinecone Marketplace API using project-scoped API keys, including the Api-Key header, key scoping, and deployment permissions.

<Note>
  This feature is in [public preview](/release-notes/feature-availability).
</Note>

The Pinecone Marketplace API uses Pinecone API keys for authentication. You can use the same API key you use for Pinecone Assistant and the Pinecone Vector Database.

## API key header

Include your API key in the `Api-Key` header on every request:

```bash curl theme={null}
curl https://api.pinecone.io/marketplace/deployments \
  -H "Api-Key: $PINECONE_API_KEY" \
  -H "Content-Type: application/json"
```

## Scoping

API keys are scoped to a Pinecone project. Marketplace deployments are scoped to a project as well. An API key can manage deployments in the project it belongs to.

For details on how to create and manage Pinecone API keys, see [Manage API keys](/guides/assistant/admin/manage-api-keys).


# Connectors
Source: https://docs.pinecone.io/reference/api/marketplace/connectors

Marketplace Connectors API reference for attaching source connectors, updating configuration, and triggering syncs across deployments.

<Note>
  This feature is in [public preview](/release-notes/feature-availability).
</Note>

The Connectors API lets you configure source connectors and review sync status for deployments.

## Operations

| Operation          | Description                                                 |
| ------------------ | ----------------------------------------------------------- |
| List connectors    | Return the connectors attached to a deployment.             |
| Attach a connector | Attach a source connector to a knowledge base.              |
| Update a connector | Update connector configuration, such as the selected scope. |
| Detach a connector | Remove a connector from a knowledge base.                   |
| Get sync status    | Return the latest sync status per file.                     |
| Trigger a sync     | Force an immediate sync run.                                |

For the operator-facing guides, see [Connectors overview](/guides/marketplace/connectors-overview).


# Deployments
Source: https://docs.pinecone.io/reference/api/marketplace/deployments

Marketplace Deployments API reference for listing, creating, updating, and deleting knowledge application deployments programmatically.

<Note>
  This feature is in [public preview](/release-notes/feature-availability).
</Note>

A deployment is the unit you configure, publish, and operate. The Deployments API lets you list, create, update, and delete deployments without using the Marketplace console.

## Operations

| Operation           | Description                                                 |
| ------------------- | ----------------------------------------------------------- |
| List deployments    | Return all deployments in a project.                        |
| Create a deployment | Create a deployment from a template.                        |
| Get a deployment    | Return the configuration and status of a single deployment. |
| Update a deployment | Update the building version of a deployment.                |
| Delete a deployment | Delete a deployment and its versions.                       |

For the operator-facing guides, see [Create a deployment](/guides/marketplace/create-a-deployment).


# Evaluations
Source: https://docs.pinecone.io/reference/api/marketplace/evaluations

Marketplace Evaluations API reference for triggering evaluation runs, retrieving scores, and inspecting per-question detail per version.

<Note>
  This feature is in [public preview](/release-notes/feature-availability).
</Note>

The Evaluations API lets you trigger evaluations and retrieve results per version.

## Operations

| Operation             | Description                                                              |
| --------------------- | ------------------------------------------------------------------------ |
| List evaluations      | Return all evaluation runs for a deployment.                             |
| Get an evaluation     | Return aggregate scores and per-question detail for a single evaluation. |
| Trigger an evaluation | Run an evaluation against the active version on demand.                  |

For the operator-facing guides, see [Evaluations](/guides/marketplace/evaluations).


# Events and analytics
Source: https://docs.pinecone.io/reference/api/marketplace/events

Marketplace Events and Analytics API reference for streaming deployment event logs and reading conversation and feedback counters.

<Note>
  This feature is in [public preview](/release-notes/feature-availability).
</Note>

The Events and Analytics API lets you stream the deployment event log and read analytics counters programmatically.

## Operations

| Operation     | Description                                                                                     |
| ------------- | ----------------------------------------------------------------------------------------------- |
| List events   | Return events for a deployment, with filters by category, version, knowledge base, and outcome. |
| Stream events | Subscribe to new events as they occur.                                                          |
| Get analytics | Return counters such as conversation volume, refusal rate, and feedback summary for a window.   |

For the operator-facing guides, see [Analytics and event logs](/guides/marketplace/analytics-and-event-logs).


# Pinecone Marketplace API
Source: https://docs.pinecone.io/reference/api/marketplace/introduction

Pinecone Marketplace API reference overview covering deployments, templates, connectors, versions, evaluations, and analytics endpoints.

<Note>
  This feature is in [public preview](/release-notes/feature-availability).
</Note>

The Pinecone Marketplace API gives you programmatic access to the same operations available in the Marketplace console: managing deployments, templates, connectors, versions, evaluations, and event logs.

During public preview, endpoint paths, request shapes, and response shapes may change before general availability.

## Resources

| Resource                | Description                                                            |
| ----------------------- | ---------------------------------------------------------------------- |
| Deployments             | Create, configure, and manage knowledge applications.                  |
| Templates               | List the catalog of vertical templates available to your organization. |
| Connectors              | Configure source connectors and review sync status.                    |
| Versions and publishing | Create building versions, publish, and roll back.                      |
| Evaluations             | Trigger and retrieve evaluation results per version.                   |
| Events and analytics    | Stream the deployment event log and analytics counters.                |

For the operator-facing guides, see [Pinecone Marketplace](/guides/marketplace/overview).


# Templates
Source: https://docs.pinecone.io/reference/api/marketplace/templates

Marketplace Templates API reference for listing vertical template catalogs and retrieving default operating parameters for deployments.

<Note>
  This feature is in [public preview](/release-notes/feature-availability).
</Note>

The Templates API lets you list the catalog of vertical templates available to your organization.

## Operations

| Operation      | Description                                                                                               |
| -------------- | --------------------------------------------------------------------------------------------------------- |
| List templates | Return the catalog of available templates with their default operating parameters and recommended layout. |
| Get a template | Return the full configuration of a single template.                                                       |

For the operator-facing guides, see [Templates overview](/guides/marketplace/templates-overview) and [Template catalog](/guides/marketplace/template-catalog).


# Versions and publishing
Source: https://docs.pinecone.io/reference/api/marketplace/versions

Marketplace Versions API reference for publishing building versions, listing version history, and rolling back deployments programmatically.

<Note>
  This feature is in [public preview](/release-notes/feature-availability).
</Note>

The Versions API lets you publish building versions, list version history, and roll back to a previous version programmatically.

## Operations

| Operation         | Description                                                                                 |
| ----------------- | ------------------------------------------------------------------------------------------- |
| List versions     | Return the version history of a deployment.                                                 |
| Get a version     | Return configuration, status, and evaluation result for a single version.                   |
| Publish a version | Promote a building version to active. Returns immediately and provisions in the background. |
| Roll back         | Promote a previous version to active.                                                       |

For the operator-facing guides, see [Publish a deployment](/guides/marketplace/publish-a-deployment) and [Manage versions and rollback](/guides/marketplace/manage-versions-and-rollback).